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Preface 


This editioa of the Paaenl-2 User Manual for the RT-11 operating system corresponds to the latest 
software release and describes all of the features of Version 2.1 of the Pascal-2 software. This manual 
is printed looseleaf to allow ns to send future errata as Update Packages with “change pages” to be 
inserted in the existing manuals. Update Packages are sent with new releases when changes made to 
the software require new or different explanations in the manual. New releases of software, including 
a set of release notes, are sent to licensed users of the Pascal-2 compiler approximately every six 
months. 

We are grateful to the many readers whose thoughtful and perceptive suggestions have helped us 
improve our manuals. Please dll out and return the evaluation report provided at the end of this 
manual, or address your comments directly to: 

David Spencer, Manager 
Technical Publications 
Oregon Software 
6915 SW Macadam Ave. 

Portland, Oregon 97219 

We appreciate hearing from you. 


Thanks to... 

Oregon Software got its start at OMSI—the Oregon Museum of Science and Industry. OMSI is a 
private educational organization chartered "to enhance the general public understanding of science 
and technology, with a strong commitment to education,” particularly of youth. It was in the 
Research Laboratory at OMSI that we began writing software. Seven of us came from OMSI to 
found Oregon Software in September, 1977. Because of the close association, the name “OMSI” 
stayed with us for a while, and we continue to support OMSI and its educational programs. 

As part of our own research, we’ve been using and distributing T^X, a text-processing system 
developed by Don Knuth at Stanford University. This publication is typeset in the Computer Modern 
Roman family of type faces with the T£X system. Draft versions were produced at Oregon Software 
on an Imprint-10 laser printer driven by T^X-in-Pascal and our VAX-11/780. 

Special thanks to Barbara Beeton and Monty Nichob for their encouragement and assistance with 
I£X and to David Kellerman and Barry Smith for implementing T£X at Oregon Software. 
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Pascal-2 V2.1/RT-11 Introduction 

Pascal-2 is an integrated system for software development. At the heart of the system is a trans¬ 
portable multipass compiler that adheres to the Pascal standard while performing optimisations 
to generate compact, fast code. The Pascal-2 system also offers sophisticated error checking dur¬ 
ing compilations, extensive error reporting and recovery at run-time, a Debugger to examine the 
dynamic state of a running program in a high-level Pascal context, plus other development utilities. 
Together, these components offer the professional programmer a structured and unified environment 
in which to design, code, test, maintain, and improve software. The result should be the production 
of more reliable programs in less time than with other programming packages. Further, use of the 
Pascal-2 compiler will allow programs to be transported to other computer systems with a minimum 
of change, thereby accelerating future software development. 

Developed over several years, Pascal-2 grew out of our experience with our first Pascal compiler, 
Pascal-1. Pascal-1 is a one-pass compiler specific to Digital Equipment Corporation’s PDP-11 series, 
with low-level extensions giving the programmer control over the PDP-11 hardware and operating 
system. Pascal-2 is larger and compiles more slowly than Pascal-1, but Pascal-2 produces code that 
is much smaller and faster than Pascal-1 code. Typical programs are 30 to 40 percent smaller and 
up to twice as fast. 



The Pascal—2 Software Development System 

The Pascal-2 system consists of the Pascal-2 compiler, the support library, the formatters 
PASMAT and PB, the Debugger and Profiler, and the cross-references XREF and PROCREF . 
The text formatter PROSE, not shown, is also a component of the system. The user creates 
the Pascal source program, the included source files, and user libraries . The Text Editor and 
Linker are supplied by the computer vendor . 





















Pascal-2 V2.1/RT-11 Introduction 


About Version 2.1 

Version 2.1 of the Pascal-2 software represents the first major technical improvement in the Pascal-2 
software since its release in 1981. The product now includes conformant array parameters, raising 
the compiler to Level 1 of the proposed international standard. The implementation of lazy I/O 
changes the way Pascal-2 performs input operations, where input is not read until it is actually 
needed. Numerous compiler and support library bugs have been fixed. Run-time error diagnostics 
now include a procedure-by-procedure walkback from the point of error to the main program and 
are capable of trapping I/O errors, allowing users to recover from I/O errors with their own code. 
Users may change the wording of run-time error messages and print additional information about 
the error for debugging purposes. 

Enhancements of the Pascal-2 software are summarized in the following list; detailed explanations 
of each feature appear in the appropriate sections of the manual. 

Summary of Changes, New Features in V2.1 Software 


Feature 

Lazy I/O 

Conformant Array 
Parameters 

Run-Time Errors 


‘Nowalkback’ Switch 

I/O Error Trapping 
‘Workspace:!!’ Switch 

Support Library 

Predefined Procedures 

Files 


Function 

An I/O scheme in which data is not read until actually used in the 
program. 

Allows you to write general procedures that accept array parameters of 
different size and with different lower and upper bounds. 

Additions include new error numbers and messages, and explanations 
of those messages. User processing of run-time errors gives you control 
of run-time error reporting. You may change the wording of run-time 
error messages and print additional information about the error. The 
run-time error walkback aids in diagnosis of run-time errors, pinpointing 
the location of the error in Pascal source terms and showing the reverse 
sequence of procedure calls leading to the error. 

Disables the error walkback. Available as either compilation or embedded 
switch. This switch is “off” by default (the walkback is printed). 

You can now recover from I/O errors with your own code. 

Reduces/increases the work space required by the compiler to compile a 
program. 

Library entry points now have the form P$nnn, where non is an integer 
in the range 0..135. Most routines are now called in the same way as 
other Pascal procedures, using the standard Pascal calling sequence. 

New procedures getpos and setpos simulate random access to files of 
type text. Function space determines the amount of stack and heap 
available to an executing program. New procedures rename and delete 
allow you to rename or delete files from within a program. 

Files opened local to a procedure are now closed upon procedure exit. 
Also, the IK: option allows you to specify the device to which the 
compiler directs its working data files. 


Eight-Bit Characters Allows you to use extended character sets. 
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About Version 2*1 


Summary of Changes, New Features in V2.1 Software (cont.) 


Feature 


Function 


Non-Decimal Allows the use of integers in radices ranging from base 2 (binary) to base 

Integer Constants 16 (hexadecimal). 


Size Restrictions 


Easing of certain restrictions allows larger programs to be compiled. 


Expanded Unsigned The unsigned integer range is 0..65535. Unsigned functions are capable 
Integers and Functions of returning unsigned and structured values. 


String Package Includes the new routines equal, assign and assignchar. Implement¬ 

ed with conformant array parameters. Procedure delete is now named 
deletestring, to prevent conflict with the new predefined procedure 
delete. 

‘%Include’ Directive New syntax allows specification of the disk volume number of the in¬ 
cluded file. 


Because the code generated by the V2.1 compiler differs from that of V2.0, current Pascal-2 users 
must recompile existing Pascal-2 programs and external modules with the new compiler. Some 
programs may need to be changed in order to compile or redesigned to take advantage of features 
such as conformant array parameters, lazy I/O and user control of run-time error reporting. 


Pascal-2 Documentation Package 

The Pascal-2 user documentation contains information on the use of the Pascal—2 compiler and 
related utilities on Digital’s RT-11 operating systems: RT-11 V4 and V5, SJ, XM, and TSX-Plus. In 
general, we assume that readers of the manual are programmers familiar with Pascal and the RT-11 
operating system. Some sections assume a detailed working knowledge of the language. 

The Pascal-2 User Manual is not intended to be a Pascal textbook. Beginners can make their way 
carefully through this manual, but we refer you to the reading list in the appendix, “For More 
Information.” 

The manual consists of five major guides, as follows: 

• The User’s Guide serves as a quick overview of the Pascal-2 system, to give you a feel for how it 
works. The guide, written on a beginner’s level, takes you through the basic steps of compiling, 
correcting, and running a Pascal-2 program. The User’s Guide also has brief explanations and 
examples of some of the standard features and utilities of the Pascal-2 system. 

• The Programmer’s Guide contains detailed descriptions of compilation commands, embedded 
and low-level switches, and the low-level interface between Pascal—2 and the operating system. 
The Programmer’s Guide also contains a miscellany of information on implementation-related 
problems, divided into two broad categories: error recovery and implementation notes. Finally, 
the guide describes Pascal-2’s optimizations and provides helpful hints as to the cause of compile¬ 
time and run-time errors and ways to fix the errors. 
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• The Language Specification describes Pascal-2’s language features in detail. Since the second 
edition of Jensen and Wirth’s User Manual and Report in 1978, the language has undergone 
major changes, which are incorporated in the Third ISO Draft Proposal 7185. Because not 
everyone is familiar with that document, the Language Specification begins by summarizing 
those changes and describing the ways that Pascal-2 implements them. Thus, the guide serves 
not only as a description of our Pascal product but also as a review of the language’s evolution 
since 1978. 

• The Debugger and Profiler Guide describes two programs designed to alleviate tedious aspects 
of programming or to improve the usefulness of the Pascal—2 system. The Debugger helps find 
and correct errors that cannot be caught at compile time. The execution Profiler shows areas 
of the program in which the most time is spent. 

• The Utilities Guide describes each of the following packages: program formatters, a text format¬ 
ter, cross-reference programs, a package that helps interface assembler routines with Pascal—2 
programs, and a dynamic string package. Each utility is described in detail, with examples. 


Included with the manual is a set of release notes including the Installation Guide. 


For information on the RT-11 system, see these RT-11 manuals: Introduction to RT-I1, System 
User’s Guide , Software Support Manual, System Utilities Guide . 


In addition, Pascal-1 customers upgrading to Pascal-2 should refer to the Pascal 2 Conversion Guide 
and the CONVRS utility, which are available from Oregon Software. The Conversion Guide explains 
specific language differences between Pascal—I and Pascal—2 and the practical progr ammi ng problems 
created by the differences. The guide describes the use of the CONVRS utility to help isolate areas 
in a Pascal-1 program that will have to be modified to convert to Pascal—2; the guide then details 
the steps required to convert the programs. The Conversion Guide concludes with a list of solutions 
to errors that you may encounter while completing the conversion to Pascal-2. 


Style Notes 

The Pascal-2 User Manual follows these style conventions: 



Text: 


Pascal reserved words, predefined symbols, switches and compiler directives are in boldface 
typewriter type: begin, write, % include, nomain. Portions of examples referred to in 
text are in boldface typewriter type. System directives are in upper-case boldface typewriter 
type: .SETTOP, .CALFIP. Program and system names are in upper case: ROTAT, RT-11. 


Program Examples: 

Commands that you should type are in underlined boldface typewriter: RUN EX . These 
commands assume a carriage return at the end. 


Program Listings: 

The Pascal-2 compiler accepts any combination of upper-case and lower-case characters. 
Examples in this manual have Pascal words in lower case and have user-defined words 
with an initial capital letter and other capitalization as needed for readability, as shown 
in this program fragment: 


procedure Show; 
begin 

SomeUserAction; 
writeIn(Result); 
end; 
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Style Notes 


Single quotes (\.*) in examples and in text appear as 1 .. 1 . 

Terminology: 

We use standard terms as they are used in documents describing the RT-11 operating 
system. 


Support Policy 

The license fee for your Pascal-2 system includes one year of software support, which covers the 
following: 

Telephone assistance. Well provide a quick cure to your problem if at all possible. 

Formal, written response to all problems, suggestions, and comments received in writing. For 
complex problems, we need written descriptions of your technical problem to ensure correct 
diagnosis and repair. (This service does not include applications consultation.) 

A no-cost update to the latest revision of the Pascal-2 system, upon the written request of your 
Designated Contact Person. This is the standard response to bugs that have been fixed. (We do 
charge for the media used for the update.) 

The Oregon Software Pascal Newsletter, which contains status reports on all of our Pascal 
products, announcements of new versions of software and new products, and various technical 
articles. 

Support may be renewed annually. Customers of an Oregon Software distributor should contact 
their distributor for support. 




xvu 
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Introduction to the User Guide 

This is the introductory section, the User Guide. It explains: 

• How to compile and run Pascal programs; 

• How to interpret program listings and error messages; 

• Some details of the compilation process. 

This guide assumes that you are familiar with: 

• Simple RT-11 commands; 

• A text editor (e.g., EDIT, TECO, KED); 

• Elementary Pascal programming. 

This guide is not: 

• An introduction to Pascal (see Programming in Pascal by Peter Grogono); 

• A detailed description of Pascal-2 (see the Language Specification, and Doug Cooper’s Standard 
Pascal User Reference Manual); 

• An expert's guide to Pascal-2 (see the Programmer’s Guide). 


Getting Started 

The first step in running a Pascal program is to enter the program into the computer and store it in 
the file system. Use a familiar text editor to enter the program; store it in a file with the extension 
.PAS. The Pascal-2 compiler accepts free-format program files, so use blanks, tabs, new lines, and 
form feeds as desired to help make the program readable. 

This Pascal version of a program is called the source program, or the souree file. All other versions 
of the program are translations from the source program. 


Compiling thu Program 

After editing, you must compile the program—translate it into a form that the computer can 
execute—and link it to the Pascal-2 support library. With the compiler and the support library 
on the system disk and with a source file called TESTPAS, the entire compilation process follows 
this example: 

B PASCAL 
• TEST 

• IIP TEST. ?I; PASCAL 

As the example shows, the PAS extension may be omitted from file names on commands to the 
Pascal-2 system but must be included in commands to other RT-11 systems such as the editor. 
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To illustrate the compilation process, let’s say that the program 

prograa First (ostpst); 
heels 

write ('•Thisgs are best is their beginnings"); 
writeln (• — Blaise Pascal'); 
end. 

is stored in the file FIRST.PAS. 

Compilation proceeds as follows: 

R PASCAL 
» FIRST 

!.TI¥ FIRST .ST; PASCAL 

•B91 FIBSI . , 

■Things are beet la their beginslags* — Blaise Pascal 

Notice that no errors were detected. The next example shows what happens if detectable errors are 
present in the source program. 

Cheeking For Errors 

The Pascal-2 compiler detects nearly 150 types of “grammatical" errors is a program: errors in 
syntax such as missing semicolons, undefined identifiers, missing begin and ead reserved words, and 
similar mistakes. As an example, the following program contains a deliberate error: a semicolon is 
missing between the program heading and the reserved word begin. 

prograa Second (oatpat) 
begin 

writela ('Things get worse as they coatiane'); 
end. 

Semicolon errors (the most common errors made by beginning Pascal programmers) are always 
detected by the compiler: 

- B PASCAL 
. SECDID 

Pascal-2 RT11 SJ T2.1D 9-Feb-64 7:06 AX Site #1-1 Page 1-1 

Oregon Software, 6918 ST Macadan Awe., Portland, Oregon 97219, (B03) 248-2202 
SECOID 

1 prograa Second (oatpat) 

‘19 

19 : Uit to separate statements 


mi There was 1 line with errors detected ••• 

TErrors detected: 1 

For each detected error, a line of the source program is printed, then an arrow indicating the 
approximate position of the error, then a message describing the error. (The number “19” a the 
error message number generated by the compiler.) See Appendix A of the Programmer s Guide for 
a complete list of detectable compilation errors. 
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Errors Detected at Run-Time 

The errors discussed so far have been compilation errors — errors detected by the compiler. Run¬ 
time errors, on the other hand, occur when a program is executing, after it has been compiled and 
linked. 

A run-time error such as “array subscript out of bounds* stops the program at the point of error. 
The Pascal-2 error reporting system prints header information and the error message, then traces 
the program’s execution history, procedure by procedure, from the point of error back to the main 
program. The error traceback, or “walkback,* is intended to make debugging easier by showing 
precisely where the program stopped and which procedures were called to reach that point. 

The following is an example of a run-time error and procedure walkback. (The program has already 
been compiled and linked.) Line numbers appearing in the walkback correspond to line numbers in 
the source listing, not line numbers in individual procedures. 

. R PASCAL 
♦ CUSTOM 

PASCAL—Fatal error at user PC= 7244B 
Array subscript out of bounds 

Error occurred at line 64 in procedure write lastname 
Last called from line 90 in procedure buildcustomerfile 
Last called from line 103 in program customs 

The first line of the walkback contains header information about the program and gives the type of 
error (fatal or I/O) and the program counter at the time of the error. 

The second line of the walkback is the error message issued by the error reporting system. Appendix 
B of the Programmer’s Guide contains a list of run-time errors and a short explanation of what may 
have gone wrong. (If the error is I/O-related, an additional line is printed that provides the system 
I/O error code and the name of the file causing the error.) 

The third line shows the location of the error in terms of source program lines. The remaining lines 
of the walkback indicate the reverse order in which the procedures were called. 

Pascal-2 also includes the capability to trap and recover from run-time I/O errors and to print 
additional information about the error. See the Programmer’s Guide for discussion of these more 
advanced techniques. 
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The Program Listing 

Many times, to correct an error, you need to see more of the program than just the line on which 
the error appears. The Pascal-2 compiler can be directed to display the entire program, with all 
detected errors and other information. This is the “listing* of the program. 

To obtain a listing file (.LST), include the list switch in the compilation command line: 

. R PASCAL 
♦ SECOND/LIST 

To get a program listing at a terminal, specify TT: as the listing file, as shown below. The listing 
also may be written to the line printer or a disk file. 

. R PASCAL 

♦ THIRD.TT: = THIRD/LIST 

Pascal-2 RT11 SJ V2.1A 6-Aug-03 7:04 PM Site #1-1 Page 1-1 

Oregon Software, 2340 SV Canyon Road, Portland, Oregon 97201, (503) 226-7760 
THIRD.TT: = THIRD/LIST 

1 program Third (output) 

-19 

♦♦♦ 19: Use 1 to separate statements 

2 begin 

3 writeln ('Things get hazy if you stare at them 1 ); 

4 end. 

♦♦♦There was 1 line with errors detected ♦♦♦ 

The listing is printed in pages, with a heading on each page showing the program name, the exact 
version of the Pascal-2 compiler, the date and time, and the licensed user identification. The listing 
also prints out, in the left-hand column, the line number for each line of the program. You also may 
use the errors switch to create a listing file containing only the lines with detected errors. 

As illustrated in the above example of list, a compilation switch modifies the compilation process 
in some way. A switch is signified by a slash and a descriptive name. The Programmer’s Guide 
describes all of the compilation switches, but the next examples show the most commonly used ones. 
The examples also demonstrate some of the features of the Pascal-2 package — the Debugger, the 
Profiler, and the PASMAT formatter, and double-precision real number format. 

The Formatter 

Suppose you have a program, EFACT.PAS, that calculates an approximation of e, the base of the 
natural logarithms, by summing the series 

1 4-1/1! + 1/2! + 1/3! + ... + 1/iV! 

until additional terms do not affect the approximation. 
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Remember that the compiler will accept a program in whatever format you choose. So the program 
may look like this: 

program Efact(output); 
var E, Delta, Fact: real; 

N: integer; 
begin 

E:=l.0; N:=l; Fact:=1.0; Delta:=1.0; 

repeat 

E:=E+Delta; 

N:=N+1; Fact:=Fact*N; Delta:=1/Fact; 
until E = (E+Delta); 
writeCfith 1 , n:l, 1 terms, '); 
writelnOthe value of e is* ,E: 18:15) ; 
end. 

To make the program more readable, you decide to format the program with PASMAT, one of the 
Pascal-2 utility programs. Give the following command: 

, R PASMAT 
♦ EFACT 

and the program is reformatted to look like this: 
program Efact(output); 

var 

E, Delta, Fact: real; 

N: integer; 

begin 

E := 1.0; 

N := 1; 

Fact := 1.0; 

Delta := 1.0; 
repeat 

E := E + Delta; 

N := N + 1; 

Fact := Fact * N; 

Delta := 1 / Fact; 
until E = (E + Delta); 
write('With 1 , n:l, 1 terms, '); 
writeln('the value of e is',E:18:15); 
end. 

(PASMAT has many other formatting options. See the Utilities Guide for details.) Now proceed to 
compile the program. 

. R PASCAL 
♦ EFACT 

. LINK EFACT.SY:PASCAL 

. RUN EFACT 

Vith 11 terms, the value of e is 2.718282000000000 
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The Debugger 

Even after you have corrected any syntax errors caught by the compiler, the program may still 
yield unexpected results. In this situation, Pascal’s interactive Debugger can help uncover and 
correct the problems. The Debugger takes control of the program and responds to your commands, 
displaying execution information in a Pascal context. With the Debugger, you can watch the progress 
of the computation, and you can display intermediate values without making any program changes. 
You can then spot the point at which values go awry and correct the error. 

To do this, use the debug switch to compile the program with the Debugger. (In most cases, you 
probably also will want to overlay the Debugger module. See the Debugger Guide for details.) 

First, compile and link the program with the commands: 

. R PASCAL 
♦ EFACT/DEBUG 

. LINK EFACT.SY:PASCAL 

The debug compilation produces four output files: EFACT.LST, EFACT.SYM, EFACT.SMP, and 
EFACT.OBJ. You need the listing file to determine the places to set breakpoints in the program. 
Don’t worry about the other three output files, but don’t delete them or the listing file. The Debugger 
uses all of them. 

After doing a debug compilation, you will find it handy to have a printout of the listing file. The 
file will look like this: 

Pascal-2 RT11 SJ V2.1A 5-Aug-83 7:04 PM Site #1-1 Page 1-1 

Oregon Software, 2340 SI Canyon Road, Portland, Oregon 97201, (503) 226-7760 
EFACT/DEBUG 


Line 

Stmt 


1 


program Efact(output); 

2 

3 


var 

4 


E, Delta, Fact: real; 

5 


N: integer; 

6 

7 

1 

begin 

8 

2 

E := 1.0; 

9 

3 

N := 1; 

10 

4 

Fact := 1.0; 

11 

5 

Delta : = 1.0; 

12 

6 

repeat 

13 

7 

E := E + Delta; 

14 

8 

N := N + 1; 

15 

9 

Fact := Fact * N; 

16 

10 

Delta := 1 / Fact; 

17 


until E = (E + Delta); 

18 

11 

writeCfith 1 , n:l, 1 terms, *); 

19 

12 

writelnCthe value of e is* ,E: 18:15); 

20 


end. 


*** No lines with errors detected ♦♦♦ 

Two columns of numbers appear on the left side of each page. The first column, labeled Line, 
numbers each line of the source program. The second column, labeled Stmt, gives the statement 
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number of the first statement on that line. The statement numbers start at 1 for each procedure 
or function, increasing by one as each statement is compiled. The Debugger uses these statement 
numbers to identify breakpoint locations in the compiled program. 

In the program Ef act, for instance, you may want to set a breakpoint at statement number 7. This 
is the point at which the approximation of e changes. If the program compiles correctly but produces 
unsatisfactory results, you may set the breakpoint at MAIN,7 to monitor the approximation to e as 
the program runs. We’ll do just that in the next example. 

Notice that the Debugger allows you to set the breakpoints. In this example, you tell the program 
to write the value of e at the breakpoint and then continue. (See the Debugger Guide for details on 
these commands.) 

. RUN EFACT 


Pascal Debugger V3.00 — 12-Aug-83 
Debugging program: EFACT 


> B(MAIN,7) <I(E);C> 

> G - 

Breakpoint at MAIN ,7 
1.OOOOOOGE+OO 
Breakpoint at MAIN,7 
2.0000000E+00 
Breakpoint at MAIN,7 
2.5000000E+00 
Breakpoint at MAIN,7 
2.6666667E+00 
Breakpoint at MAIN,7 
2.7083335E+00 


-— at breakpoint, write E and continue 

--—-start program 

E := E ♦ Delta; 

E := E + Delta; 

E := E + Delta; 

E := E + Delta; 

E := E + Delta; 


Breakpoint at MAIN,7 
2.7166669E+00 
Breakpoint at MAIN,7 
2.7180557E+00 
Breakpoint at MAIN,7 
2.7182541E+00 
Breakpoint at MAIN,7 
2.7182789E+00 
Breakpoint at MAIN,7 


E := E + Delta; 
E := E ♦ Delta; 
E := E + Delta; 
E := E + Delta; 
E := E + Delta; 


2.7182817E+00 

With 11 terms the value of e is 2.718282000000000 
Program terminated. 

Breakpoint at MAIN,12 writelnC'the value of e is 1 , E: 18: 15); 

> a --- 


quit 
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Double Precision 

The computed value in the previous examples is printed with 7 significant digits. You may need 
greater precision for some programs. To get extended precision, use the double switch, which 
computes to 15 significant digits. The double switch allows you to print a more precise value for e. 
(See the Programmer’s Guide for details.) 

. R PASCAL 
* EFACT/DOUBLE 

. LINK EFACT.SY:PASCAL 

. RUN EFACT 

With 19 terms, the value of e is 2.718281828469050 

The Profiler 

Finally, let’s examine the program for efficiency by using the profile switch and by adding the 
PRFILE module to the Linker input. “Profiling” shows the number of times each statement is 
executed, giving you the opportunity to optimize sections of code that are executed many times. 

The Profiler takes control of your program and asks for the name of the profile output file. The 
default extension is .PRO. 

. R PASCAL 
» EFACT/PROFILE 

. LINK EFACT.SY:PRFILE.SY:PASCAL 

. RUN EFACT 

profile V2.1 12-Aug-83 

Profiling program: EFACT 

Profile output file name? EFACT - Output goes to default extension 

Yith 11 terms, the value of e is 2.718282000000000 

Program terminated. 

Profile being generated 
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The output file looks like this: 

Pascal-2 RT11 SJ V2.1A 5-Aug-Q3 7:04 PM Site #1-1 Page 1-1 
Oregon Software. 2340 SV Canyon Road. Portland, Oregon 97201, (503} 226-7760 
EFACT/PROFILE 



Line 

Stmt 


1 


program Ef act (output) ; 


2 


var 


3 


E, Delta, Fact: real; 


4 


N: integer; 


5 



1 

6 

1 

begin 

1 

7 

2 

E := 1.0; 

1 

8 

3 

N := 1; 

1 

9 

4 

Fact : = 1.0; 

1 

10 

5 

Delta : = l.O; 

10 

11 

6 

repeat 

10 

12 

7 

E := E + Delta; 

10 

13 

8 

N := N + 1; 

10 

14 

9 

Fact := Fact * N; 

10 

15 

10 

Delta := 1 / Fact; 


16 


until E = (E ♦ Delta); 

1 

17 

11 

write(•With •, n: 1. • terms '); 

1 

18 

12 

writeln(‘the value of e is 1 , e: 18: 


19 


end. 


*** No lines with errors detected *** 

PROCEDURE EXECUTION SUMMARY 

Procedure name statements times called statements executed 

MAIN 12 1 57 100.00* 

There are 12 statements in 1 procedures in this program. 

57 statements were executed during the profile. 

The leftmost column of the profile listing shows the number of times each line is executed. The 
Profiler listing concludes with a “Procedure Execution Summary” that details each procedure name, 
the number of times it is called, the number of statements it contains, and the number of statements 
it executes. Note, too, that the summary shows the percent of execution count taken by each program 
block. (In this example, with only one procedure, the portion is 100%.) Given this information, you 
can attempt to optimize the procedures and statements that use a disproportionately large part of 
the time (“90 percent of the time on 10 percent of the program”). 

See the Profiler section of the Debugger Guide for more information and for a much more detailed 
example. 


Your Next Step 

Thus ends your guided tour through Pascal-2. At this point, you should be able to run a few simple 
programs. Before getting into complex programs, however, you should consult the Programmer’s 
Guide, the Language Specification, and the Debugger Guide. 
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Introduction 

The Programmer’s Guide contains nitty-gritty information abont Pascal-2 for programmers well- 
versed in the Pascal language. This guide describes compiler commands, compilation and embedded 
switches, I/O control switches, and Pascal's low-level interaction with the PDP-11. This guide also 
describes ways to handle common Pascal-related implementation questions on RT-11 and contains 
other miscellaneous information. 

This guide is not: 

• an introduction to Pascal (see Programming in Pascal by Peter Grogono); 

• a beginner’s guide to Pascal-2 (see the User Guide); 

• a detailed description of Pascal-2 (see the Pascal-2 Language Specification). 

Compiler Commands 

All Pascal-2 compilation commands are divided into three parts: the compiler invocation command, 
the file specifications, and the compilation switches. 

The compilation syntax for Pascal-2 is this: 

■ B fAS C AL 

« output-fi/c./ ist»nr-flle«/nput-fl/es/switches 

The R PASCAL invocation (or some other name that your system manager has chosen for the 
invocation command) must always come first. The prompt appears for the file specifications 
and compilation switches. 

input-fi/es: 

The only required file specification is at least one input file. Multiple input files 
are concatenated in order, from left to right, so that a large program can be split 
into separate files or so that a common set of definitions can be placed in a configuration 
file. With “source concatenation” no input file can contain a program statement, 
except for the first file listed. If no output specification is given, the output is deter¬ 
mined by the compilation switches; the file name is taken from the last input file 
specified; and the output files will be placed in the default directory. The default 
input file extension is .PAS. Multiple input files are separated by a comma. 

output-fi/e: 

The output file specifies the name of the object output, with a default extension 
of .OBJ. If the nacro compilation switch is specified, the output file contains MACRO- 
11 code and the default extension is .MAC. 

listing-file: 

The listing file specifies the file to receive the compilation or error listing. The default 
listing file extension is .LST. 

If an equal sign appears on the command line, but no file name is listed in the 
position of the output file, no output file is generated. If no file name is listed in the 
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poaitioe of the listing file, a listing output is produced only if errors exist; if errors 
exist, output is sent to the user’s terminal with the error* switch assumed. 

switches: Program compilation is affected in some way by one or more of the options described 
in the next section. Examples in this manual show the compilation switches alter the 
last file specification, but switches may appear after any file specification and wherever 
they’re placed, they apply to the entire compilation. Multiple switches are separated 
by slashes. 

Compilation Switches 

Compilation switches provide control over the files generated and over some aspects of the generated 
code. A switch is signified by a descriptive name (e.g., check). A switch name beginning with no 
reverses the effect of the switch (e.g., nocheck). A switch name may be abbreviated as long as the 
shortened form is sufficient to identify the switch. Three characters of the switch name (excluding 
the no) always identifies a Pascal-2 compilation switch (e.g., cho, aocho; aac, aoaae). 

Some switches, such as object and macro, are incompatible, causing the error message “conflicting 
switches specified” if used in the same compilation. 

Pascal-2 compilation switches are: 


Program Options 


double All real variables are in 8-byte floating-point format. Yon also must use colon notation 
(e.g., E: 18: IS) within the program to obtain double-precision values in the write state¬ 
ment. Default is “off”: real variables are in 4-byte format. See “Extended Precision” 
for more details. 

pascall Specifies that the interface to external procedures be compatible with Pascal-1. This 
interface is a bit less efficient than that of Pascal-2; the paacall switch should be used 
only when required. Default is the Pascal-2 interface. 

noaaia No main program is expected; only procedures are compiled. This switch is used most 
often to compile modules containing only external procedure definitions. If a main 
program is found, an error message is generated saying that extra statements have 
been found. Default is nnln: a main program is being compiled. 


own Specifies that global-level variables are local to the compilation unit and are shared 

only with other external routines that have been compiled with the same program 
name and with own. Default is “off”: global variables are shared. 


nowalkback 

Disables the generation of line number and procedure name tables for the procedure- 
by-procedure walkback that is displayed on the terminal when a program contains 
a run-time error. The run-time message header and error message are printed but 
not the walkback. Default is walkbsck: the tables are generated, and the full walkback 
in source terms is displayed after the message header and error message. See “Run¬ 
Time Error Reporting” later in this guide for a discussion of the walkback. The 
debug switch disables the generation of the error walkback. 


Compiler Options 
workspace:* 

By default, the Pascal-2 compiler opens about 500 blocks of work space. The workspace 
option allows you to reduce work space to compile a small program. A realistic low 
range is about 150 to 200 blocks. The error message “attempt to write past eof” 
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on a work file indicates that the compiler needs more work space for a large program. 

A realistic high range is about 750 blocks. 

errors Requests that the listing file contain only lines with errors. Unless list is specified, 
the default is “on* and errors are printed on the terminal. When list is specified, 
the default is “off* and all lines are printed in the listing file. This switch has no 
effect when used with the debug switch or the profile switch, because both of these 
switches always generate a listing file. 

list Requests a full source listing in the listing file. If a listing file is specified, the default 
is “on*; otherwise the default is “off.* 

debug Requests generation of code and auxiliary files to interface with the Pascal-2 Debugger. 

Default is “off.” The debug switch disables the generation of the walkback. This switch 
cannot be used with the prof ile switch or the errors switch. 

profile Requests an execution profile when the program is run. Default is “off.* The switch 
cannot be used with the debug switch or the errors switch. 

Code Switches 

obj ect Generates an object format output file with default extension .OBJ. Default is normally 
“on*; object code will be generated. The switch is “off* when noobject is specified or 
when no output file is provided on the command line. The switch cannot be used with 
the macro switch. 

macro Generates MACRO-11 code in the output file. This code may be assembled by the 
MACRO assembler command to produce an object file. When macro is specified, obj ect 
is set “off* and the default extension for the output file becomes .MAC. Default of 
macro is “off.* The macro switch cannot be used with the object switch. 

Checking Switches 

Disables all run-time checks, including index range checks, subrange assignment checks, 
pointer checks, stack checks, case label checks, and divide-by-zero checks. Note that 
compilation errors are still detected. Thus, if nocheck is specified, var A: array [2.. 10] 
of integer; A[l] := 0; will still be detected as a compilation error, but I : = 1; 

A [I] := 0; will not be. After a program has been fully debugged, the nocheck 
switch can be used to reduce the size of the compiled code. Default is check. 

Requests that all Pascal-2 extended language features be flagged as errors. Default 
is nostandard. 

Used in debugging the compiler. Default is “off.* 

Prints wall-clock time consumed by the compiler and the compilation rate in lines per 
minute. Default is “off.* 

Processor Switches 

The processor switch defaults to the processor option for the machine on which the compiler is 

running. Change the value by specifying exactly one of these four switches on the command line: 

fpp Requests the compiler to generate code for a machine with the Floating Point Processor 

(FPP) option. FPP instructions include ADDF, MODF, DIVF, etc. This switch implies the 


nocheck 


standard 

test 

times 
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eis switch and may not be specified at the same time as the f is switch. 

f is Requests the compiler to generate code for a machine with the Floating Instruction 

Set (FIS) option. FIS supports only the four basic floating-point instructions and is 
available on only a few types of machines. This switch implies the eis switch and may 
not be specified at the same time as the f pp switch. 

eis Requests the compiler to generate code for a machine with the Extended Instruction 

Set (EIS) option. The EIS processor option includes instructions to perform integer 
multiplication and division. Floating-point operations will be done with calls to a 
floating-point simulator. 

sim Requests code with calls to software routines for integer multiply and divide as well as 

for floating-point arithmetic. Should be used only if the target machine does not have 
EIS. 


Embedded Switches 


Some characteristics of the compiled code may be controlled by switches included in the source code. 
These switches take the form of a Pascal comment beginning with a dollar sign ‘$’ and followed by 
a descriptive name, for example: 

{$indexcheck} 


A switch name beginning with “no* reverses the effect of the switch, for example: 

{$noindexcheck> 


Most switches may be abbreviated to a minimum of three characters, for example: 

{$ind> or {$noi> 

However, when using Snopointorcheck and $nopro£lie be sure to enter more than three characters, 
or the compiler will treat the switch as an ordinary comment. 

Multiple switches can be embedded within a single comment. The switches must be separated by 
commas; only the first may have the dollar sign. The following forms are equivalent: 


{$noindex,norange} 
{$noindexH$norange> 


Embedded switches are counting switches. Each occurrence increments or decrements the switch 
value; the switch is enabled if its value is greater than zero. The initial value of a switch is controlled 
by an equivalent compilation switch, such as debug, if the equivalent compilation switch exists. If 
no equivalent switch is present on the command line, the initial value is determined by the defaults 
described below. 

Once set, some switches are valid for the entire program, as with $own. In some cases, the “no” form 
of the switch is the one normally used, as with $nomain. 

Some switches may be turned a on” and “off” for a particular section of code, either on a statement- 
by-statement or procedure-by-procedure basis. The following example shows how debugging can be 
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turned off for a procedure: 


{$nodebug> -debugging turned off 

procedure P; 
begin 

: -body of procedure P 

end; 

{$debug> -debugging enabled again 


The particulars of each switch are described in the following sections. 

Program Options 

$double Specifies that all real arithmetic is to be done with double precision rather than with 
single precision. $double applies to the entire compilation. You also must use colon 
notation (e.g., E:18:15) to print the double-precision values in a write statement. 
This switch must appear in the program before any data of type real is defined or 
used. Default is “off.” 

Spascall 

Specifies that external procedures will be called in a manner compatible with Pascal-1. 
This switch may slow program execution but should simplify conversion of programs 
from Pascal-1 to Pascal-2. The default is “off.” 


External Pascal-2 procedures may be called regardless of the setting of this switch. 

Snomain No main program is expected; only procedures are compiled. This switch is used most 
often to compile modules containing only external procedure definitions. If a main 
program is found, an error message is generated saying that extra statements have 
been found. Default is $main: a main program is being compiled. 

$own Specifies that global-level variables are local to the compilation unit and are shared 
only with other external routines that have been compiled with the same program 
name and with $own. $0wn applies to the entire compilation. Default is “off”: global 
variables are shared. 


$nowalkback 

Disables the generation of line number and procedure name tables for the procedure- 
by-procedure walkback that is displayed on the terminal when a program contains 
a run-time error. The run-time message header and error message are printed but 
not the walkback. Default is walkback: the tables will be generated, and the full 
walkback in source terms will be displayed following the message header and error 
message. The debug compilation switch disables the generation of the error walkback. 
See “Run-Time Error Reporting* later in this guide for a discussion of the walkback. 

Compiler Options 

$nodebug, $debug 

Disables/enables some of the overhead of the Pascal-2 Debugger. These two switches 
will have effect only when the debug compilation switch is specified. The debug switch 
generates the extra files needed for debugging and sets the Sdebug switch “on.* 
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{Nodebug can be used to turn off some of the debugging overhead for procedures 
or functions that have already been fully tested. $Debug can be used to restore debug¬ 
ging for other procedures. 

{noprofile, {profile 

Disabies/enables some of the overhead of the Pascal-2 Profiler. These two switches will 
have effect only when the profile compilation switch is specified. The profile switch 
generates the extra files needed for profiling and sets {profile “on.” {Noprofile 
can be used to turn off profiling for procedures or functions that do not need to 
be profiled, and {profile can be used to restore profiling for other procedures. 

When the begin statement of a procedure is compiled, the state of the {debug/{nodebug 
and {prof ile/{noprof ile switches will determine debugging or profiling for that 
entire procedure. Note that a procedure constitutes the smallest section of code that 
can be debugged or profiled; you can’t debug or profile individual lines of a procedure. 

The {debug/{nod®bug and {prof ile/{noprof ile switches serve the same functions 
as far as the code generated. You would never use both sets in the same compilation. 
(You can’t debug the program and profile it at the same time.) 

{nolist Turns off the listing of source lines in the listing file; {list restores the listing of source 
lines. The switch may be turned on or off after each line of source code. The listing file 
will display the {nolist/{list switches, and the line numbers will reflect the lines for 
which listing has been disabled. In this program fragment, listing has been disabled 
on lines 3 through 5: 

1 program Ex(output); 

2 {{nolist} 

6 {{list} 

7 

8 begin 


Lines with errors will be displayed even if the {nolist switch is on. Default is {list. 

Do not use the {nolist switch during debugging sessions. If you attempt to access 
any “unlisted” line(s), the response will be the message “No such statement in this 
procedure.” Other errors also may be produced. 


{standard 

Like the corresponding compilation switch, {standard causes all extended language 
features of Pascal-2 to be flagged as compilation errors. By using the embedded 
switch at the beginning of the program, you don’t have to use the standard switch 
every time you compile the program. 

In addition, if you want to compile the program using language extensions of Pascal-2, 
but you want to mark the non-standard features (for later transportability to another 
compiler, perhaps), insert the {standard switch at the start of the program, and 
enclose any non-standard sections with the switches {nostandard and {standard. The 
compiler will then check the rest of the program for non-standard features, so that 
you can minimize your use of extensions. The {nostandard switch will be a textual 
flag to aid any future conversion to a standard program. 

The {standard and {nostandard switches may be turned on or off after each line of 
source code. Default is {nostandard, which accepts the extended language features of 
Pascal-2 as correct forms. 
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Run-Time Checking Switches 

The compilation switch nocheck will turn off all run-time checks. The embedded switches listed 
below will cancel the particular checks listed below. Any of these switches can be placed at the start 
of the program to turn off a particular kind of check throughout. Or, “on/off* pairings can be used 
on a statement-by-statement basis within the program. 

Turning off run-time checks will reduce the size of the program. However, we recommend that you 
do not turn off any checks until the program has been fully debugged. 

$noindexcheck 

Stops generation of code for array bounds checks; no array index is checked as to 
whether it is within the array bounds. Default is $ixidexcheck. 

$nopointercheck 

Stops generation of code that checks for nil or invalid pointer values. Default is 
)po intercheck. 

$norangecheck 

Cancels the subrange assignment and case statement check capabilities. No assign¬ 
ment to a variable of subrange type is checked as to whether the assigned value 
is within the allowed range. Also, case selectors are not checked for matching labels. 
Default is $rangecheck. 

$nostackcheck 

Stops the generation of code for stack overflow checks on procedure and function 
entry. No entry to a procedure or function is checked as to whether adequate stack 
space is available for local variables. Note that some procedures call support library 
routines that check for stack overflow. Thus, even when compiled with this switch, 
some programs may still report “stack overflow” errors. The default is $stackcheck. 

Compilation Examples 

The following examples show the effects of various switches on the compilation. 

Example 1. 

. R PASCAL 
♦ PROG/LIST 

Compiles the file PROG.PAS and generates an object file PROG.OBJ and a listing file PROG.LST. 
The check switch is assumed to be on, and code will be generated for the hardware options of the 
machine on which the program is being compiled. 

Example 2. 

. R PASCAL 
♦ PROG,PROG=PROO 

Equivalent to Example 1. 

Example 3. 

. R PASCAL 

» PRQG=PROG/NQCHECK/FIS 

Compiles the file PROG.PAS and generates an object file PROG.OBJ. Any errors will be listed on 
the user’s terminal. No run-time checking code is generated, and code will be generated for a CPU 
with FIS instructions. 
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Example 4. 

. R PASCAL 

♦ HEADER.MIDDLE.PROCED/NOMAIN 


Concatenates and compiles the files HEADER.PAS, MIDDLE.PAS, and PROCED.PAS in the order 
given, and generates an object file, PROCED.OBJ. This code has no main body and therefore 
contains external procedures. The check switch is assumed to be on, and code will be generated for 
the hardware options of the machine on which the program is being compiled. 

Example 5. 

. R PASCAL 
♦ .TT:=PRQG 

Produces a listing file to the terminal but no PROG.OBJ file. 


Linking and 


Executing 


After compilation, Pascal-2 programs must be linked to the support library before being executed. 
The DCL sequence is: 


. LINK PROG.SY:PASCAL 

. RUN PROG 

The preceding two commands may also be entered in following manner as well: 
. R LINK 

♦ PROG = PROG.SY:PASCAL 

*zc 

. RUN PROG 


See “The Linker, Overlays, and the Librarian* for details of the link process. 
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I/O Control Switches 

The reset and rewrite standard procedures accept two additional arguments specifying the file 
name of an external file and default fields of the file name. These arguments can also include 
I/O control switches that give explicit control of the operating system interface details. (A fourth 
parameter can also be specified. See the Language Specification for a complete discussion of reset 
and rewrite.) 

The I/O switches appear in the file name or default name parameters as shown in these examples: 
rewrite (F,' data. dat/seek/span/size: 12. 1 ,ErrStatus) ; 

A special device (TI:) also may appear in the reset and rewrite calls. The TI: device connects to 
the Pascal-2 terminal driver and is used in place of the TT: driver for interactive use. 

A complete list of I/O switches appears below, followed by individual details. All switches may be 
abbreviated to the first two letters. The parameter n is a octal number unless terminated by a period, 
in which case it is a decimal number. 

Switch Meaning 

/buffersize: n Allocate n bytes for buffer (hereafter abbreviated /buff) 

/go Allow programmed error handling 

/nf s Non-File-Structured access 

/odt Single-character terminal input 

/seek Direct-access file 

/size: n File storage allocation 

/span Records span block boundaries 

/temp Temporary file 

/buff :n (Buffersize): The /buff :n switch specifies the storage to be allocated to a file buffer. 

Pascal-2 normally allocates the minimum space required for a file buffer, 512 bytes. For 
disk files this default value may be raised by multiples of 512 to improve the efficiency 
of I/O transfers, at the cost of additional memory. Line-oriented files such as terminal 
and line-printer files receive buffer space equal to the width of the line, usually 80 
characters. Efficient single-character I/O requires a minimum of buffer space, 1 or 2 
characters. See also the /odt switch below. 

The value of n used with /buff :n is a decimal number if terminated with a period; 
otherwise octal. 

/go (I/O Error Continue): I/O transfer errors are normally fatal and cause immediate 

program termination. The /go switch indicates that I/O errors on the specified file are 
non-fatal and allow the program to continue executing. This switch is the equivalent 
of noioerror, one of three predefined Pascal procedures that trap and respond to 
I/O errors. See the section tf I/0 Error Trapping.” The switch /go has been left in for 
compatibility with previous implementations. 

/nf s (Non-File-Structured Access): The /nf a switch is used to achieve non-file-structured 

access to a device that is normally file-structured, such as a disk device. Because direct 
access to such a device can destroy its directory structure, Pascal-2 prevents non-file- 
structured access unless the /nf s switch is used. 

/odt (Single-Character I/O): The /odt switch derives its name from the ODT Debugger 
(Octal Debugging Technique), which is driven by single-character commands. The /odt 
switch is used with keyboard files, indicating that each character read from the file 
is to be processed immediately without any wait for a carriage return or other action 
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character. The /odt switch is only effective for files on the TI: terminal device, and 
the size of the buffer should be reduced to a minimum, as shown: 

reset(input, 1 ti:/odt/bulf:2 1 ); 


Note that the RUBOUT and Control-U (~U) keyboard editing capabilities are not effective 
with /odt. 

/seek (Direct-Access): The /seek switch enables the use of the direct-access seek procedure, 

and it permits both read and write access to the file variable so that records may be 
updated with calls to get and put. The seek procedure is described in the Language 
Specification. 

/size:n (File Allocation): The /size:n switch used in the rewrite procedure specifies the 
space to be allocated for the file. The size of the file is given in blocks of 512 bytes. 



/span 


/temp 


(Spanned): In files created or accessed by Pascal-2 programs, fixed-length records are 
normally “blocked.” This means that an integral number of records are stored in one 
disk block of 512 bytes, with any remaining storage in that block being unused. The 
/span switch packs records more efficiently, with records spanning from one disk block 
to the next. This requires additional buffer memory, which is automatically allocated, 
and some additional computation. Spanned and blocked files are not generally com¬ 
patible. Files created with /span should be read with the same switch. 

(Temporary): This switch is used with rewrite to indicate a temporary file that will 
be deleted on termination. No file name is needed if this switch appears. 


w 
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Pascal-2 implements separate compilation through the concept of an external module, a program 
fragment containing at least one procedure or function. External modules are compiled independently 
of other program units and combined by the Linker. External modules may be stored in libraries to 
simplify the handling of common routines. 

External modules may reference global variables shared by all of the modules making up a program. 
If each module (including the main program) is compiled with the same global variables, the effect 
is as if all modules were compiled together. For this to work properly, the global declarations in 
the external procedure and main program must contain the same variable declarations in the same 
order. Parameter lists also must agree (i.e., contain the same parameter declarations in the same 
order). The simplest and most efficient way to do this is to place all global declarations, including 
references to external procedures and functions, in a header file then include the header file in the 
external module and in the main program, using the fiaclide compiler directive (see “Multiple 
Source Files"). 

External modules must be referenced at the outermost (global) level of a main program, but they 
may be called from any point in the code. An external module compilation requires either the nonaln 
compilation switch or the finonaln embedded switch. Both switches specify that no main program 
is contained in the source file. The nonaln switch is specified on the command line, whereas the 
taonala embedded switch is placed at the beginning of the external module. 

An external procedure name consists of the first six characters of the procedure or function identifer. 
External procedure names must uniquely identify an external routine because they are used as global 
symbol names by the Linker. 

Linking errors most pertinent to external modules are: 

• Duplication of external symbols. An external procedure has been defined in more than one 
module. When multiple definitions are encountered, the Linker uses the first definition only and 
ignores succeeding definitions. 

• Undefined external symbols. The program has referenced an external routine that was not 
defined in any of the object files or libraries specified on the command line. This error indicates 
that the program contains unresolved global references. 

In each case, the Linker responds with an error message and produces an output file that cannot 
execute (permission bits on the file are not set). 

Two compiler directives, external and uoupaacal, allow the use of external modules. The external 
directive defines a procedure or function implemented in Pascal-2 as “external,” which means that 
the procedure may be referenced by other modules and that both the external module and the 
program or module that calls it expects to find the normal Pascal-2 calling sequence of parameters 
on the stack. The aonpancal directive defines a routine written in a language other than Pascal, 
such as FORTRAN or MACRO-11, and generates a call to the FORTRAN interface routine (Pfilll) 
in the Pascal support library. Pfilll creates the standard DEC calling sequence of parameters which 
is expected by the external module, and which differs from Pascal-2’s. 


CAUTION 

Observe two cautions when using the external or aonpancal directive. 
Parameters to external routines cannot be checked by the compiler for type 
conformance across module boundaries, so an accidental type mismatch 
may cause unpredictable results. Abo, the compiler cannot verify the con* 
formance of global data. As mentioned above, use of the linelndo directive 
can help reduce problems in this area. 
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Cells to Pascal-S Routines 

The syntax of the exteraal directive is similar to the syntax of the forward directive in that it 
consists of two distinct parts: the declaration and the body. The declaration includes the external 
procedure or function name and the argument list, followed by the external directive. 

procedure GetStringUrg: Argtype) ; -this is the declaration 

exteraal: -external directive is required 

This declaration must appear in the external module and in each compilation unit that calls that 
external routine. You can place the declaration in a header file and use the fiaclnde directive to 
insert it appropriately. 

The body of the external module contains the actual code for the procedure or function and must 
not include an argument list. 

procedure GetStrlng; -this is the procedure body 

begin 


ead; 

The body and declaration must be compiled together in order for the external procedure to function 
properly. The external procedure may then be called in the same way as any other procedure or 
function: 

GetStriag(Length) ; --external procedure call 


Example Using External Directive 

The practical application of external procedures is best shown by example. The following sample 
illustrates the declaration and use of external procedures and the correct way to access global vari¬ 
ables. Note that the global declarations must be identical in the external procedure (CHANGEPAS) 
and in the main program (MAINLINEPAS). Note also the use of the tnonaia embedded switch in 
the external procedure. 

First, we create a separate header module HDR.PAS containing the external procedure reference 
and the program's global declarations. 

HDR.PAS 


type -global declarations 

GlobalType = record 
B: boolean; 

V: Integer; 

•■d; 

var 

Glob: GlobalType; 

I: integer; 

procedure Change(P: integer); 

exteraal; -external directive must appear 

The file CHANGEPAS consists of the external procedure Change and the (include directive, as 
follows: 
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change.pas~1 

{taoaaia) -—-embedded switch 

liaclids hdr.paa —-header module 

procedars Change; --ao parameters here 

begin 

vith Glob do 

begin -change global variables 

B :* true; 

¥:*¥♦?; 

end; 

end; 

The external procedure is then compiled with the none In option embedded, using the command: 

■ B PASCAL 

s CHAlCE 

However, you can omit the embedded option and specify the nonnla on the command line in the 
following manner: 

-B P ASC A L 

eCHAlGE/BOMAIf 

The externally defined procedure Change may now be called within any program unit that includes 
HDRPAS and is linked with CHANGE.OBJ. For example, assume that the file MAINLINEPAS 
consists of this: 

MAINLINEPAS 


prograa Mainline; 

linclude hdr; -external procedure and global declarations 

procedure Before; 
begin 

with Glob do 

vritelnCBefore executing Change, B * ’,B,' and T * , .¥:2,*.*); 

end; 

procedure After; 

begin 

vlth Glob do 

vritelnCAfter executing Change, B ■*,B,* and T » , ,T:2,*.*); 

•nd; 

begin < prograa Mainline } 
vlth Glob do 

begin - initialise global variables 

B :» false; 

¥ :« 0 ; 
end; 

I :* 46; 

Before; 

Chaage(I) ; -the external call 

After; 

end. 
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Compile MAIN as any other main program and link the main program and external module, as 
shown: 

B FISCAL 
• Mill 

• B Lin 

s hill .MAI1=M1I1. CHUCK .ST: PASCAL 

Running MAIN yields these results 

- HOI Mill 

Before executing Change, B * false and T « 0. 

After executing Change, B * true and T • 45. 


Calls to Non-Pascal-3 Routines 

The aoapascal directive is used instead of external when the external procedure is generated by an 
assembler or a compiler other than Pascal-2. Idapascal creates an interface between the Pascal-2 
calling sequence generated by the main program or module and the standard DEC calling sequence 
required by FORTRAN and most MACRO routines. In addition, when the aoapascal directive is 
invoked, register R5 is used as a pointer to the list of parameters. 

Syntax for the aoapascal directive consists of a separate declaration and body. The declaration 
contains the name of the procedure or function and the argument list, followed by the aoapascal 
directive. 

Calling MACRO Subroutines 

The external declaration for a MACRO function looks like this: 
prograa Test; 

var 1: Integer; 

function afaact (var i: integer) : integer; -declaration of 

nonpascal; MACRO routine 

begin -body of the main program 

i :« 10; 

vritela(afanct(i)); 

end. 
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The MACRO routine AFUNCT is written: 

Reims arguent piss 10 


AFU1CT:: 


■Of 

•2(r6).r0 

add 

•12.r0 

rti 

pe 

.•ad 



Type matching for the declaration and use of parameters are the nser’s responsibility. 

The sample program Test is compiled with the command: 

- R MICRO 
• AFP1CT 

R PA SCAL 

• TEST 

R I II 

• TEST.TEST s TEST.ATUICT.ST:PASCAL 

• BOi TEST 

20 

MACRO routines written with the Pascal-2 PASMAC utility must be declared as external rather 
than aonpascal, because PASMAC simulates the Pascal-2 calling sequence. 
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Celling FORTRAN Subroutines 

For Pascal programs to caU FORTRAN subroutines, two conditions most be met: all parameters 
most be passed by reference, not by value, and FORTRAN sobrootines most be declared in Pascal 
programs with the aonpancal directive. 

The program FTEST.PAS shows a way to call FORTRAN subroutines from a Pascal program. 
The program reads three integers from the terminal, calls the FORTRAN subroutine ADDEM to 
calculate the sum of the three numbers, then prints the sum. 

Subroutine ADDEM.FOR contains these statements: 

SUBROUTIR ADDEM(A,B,C,D) 

C 

C ADDS A. B. C TO PRODUCE D. 

C 

IMPLICIT IITEGEM (A-Z) 

D ■ A ♦ B ♦ C 
RETUBS 
ERD 

The main Pascal program contains these lines: 

prograa FORtsst; 
var 

A. B. C, D: iategsr; 

procedure ADDEM(var A, B, C, D: Integer); 
aonpancal; 

begin 

Trite ('Enter 3 values: •); 
readlaCA. B, C); 

ADDEM (A, B, C, D); { add the auabers} -FORTRAN call 

vriteln(‘The answer is D); 
end. 
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Compile and ran the program using these commands. Assume that the FORTRAN subroutine 
ADDEM has already been compiled. 

R PASCAL 
• FTEST 
a Lin 

»FTEST=FTEST.ADDER.ST:PASCAL 

. HOI FTEST 

Eater 3 raises: 20 40 120 
The answer Is 180 

Two restrictions relate specifically to the use of FORTRAN subroutines in Pascal programs. First, 
Pascal-called FORTRAN subroutines cannot access files opened in the Pascal program. However, 
these FORTRAN routines can use files that they themselves open. 

Second, FORTRAN allows the passing of ’‘null* parameters to subroutines, in which a comma is 
used as a place holder for an optional parameter. Pascal has no such feature. To pass null parameters 
to a FORTRAN subroutine from Pascal, use the origin directive to declare the null parameter. The 
variable and procedure declaration for the Pascal program appears as shown: 

var 

Listlumber, LastList: integer; 

Hull origin 0: integer; - specifies null integer parameter for FORTRAN 

RIull origin 0: real; -specifies null real parameter for FORTRAN 

Revlnd: boolean; 

procedure FPREI(var lunber. Last: Integer; 

var I: integer; var R: real; 
var Rev: boolean); 

nonpascal; 

The FORTRAN subroutine declaration is then: 

subroutine FPREV(lnnber,Last,I,R,Rev) 

When you call the FORTRAN subroutine from the Pascal program, substitute the appropriate lull 
variable for any unnecesary parameters. In the case of FPREW, the third and fourth parameters 
are null parameters: 

FPREV (Lis tlnnber, LastList .Hull, RIull, Rewind); 
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External Module Libraries 

Suppose you want a library of procedures that can be referenced by any program. For a particular 
program, you do not necessarily reference all the procedures in that library, and you do not want 
the entire library loaded with the program. 

Procedures and functions from one compilation unit form a single object file and cannot be selectively 
loaded. For example, if procedures A, B, and C are compiled together and placed in a library, any 
reference to one of them causes all three to be loaded. On the other hand, if each procedure A, B, and 
C is compiled separately and the three object files are placed in the same library, then a reference 
to one of them causes only that procedure to be loaded in the program. To keep final program size 
to the minimum, library procedures should be compiled separately whenever possible. 

Rather than having an external declaration in the main program for each procedure needed, create 
a single “header” file containing the external declarations for all the external procedures defined in 
the library. This header file can be included in the compilation with the (laclade directive placed 
near the beginning of the program source file. No external reference is generated for any external 
procedure in the header file that is not used by the program, so only those procedures actually used 
by each compilation unit are loaded into the final image file (assuming that the library procedures 
were themselves separately compiled). See “Multiple Source Files” for use of the fincludn directive. 

By using a header file in this way, you can avoid errors that could be caused by a mismatched 
declaration, forcing any change made to a declaration for an external procedure to be reflected in all 
programs using that procedure. Carried to the fullest extent, a library and its corresponding header 
file can be used system-wide. 
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The Linker, Overlays, and the Librarian 

The Linker 

Object modules produced by the Pascal-2 compiler are compatible with object modules produced 
by the MACRO assembler, FORTRAN compiler, and other RT-11 system utility programs. The 
Linker, LINK.SAV, can produce overlaid executable programs, allowing much larger programs than 
the 32K-word address space. (Overlays are explained below.) The Librarian, LIBR.SAV, can build 
libraries of object modules. Some highlights of Linker and Librarian capabilities are covered here. 
See the RT-11 System User's Guide or the RT-11 System Utilities Manual for details. 

To run the Linker, give the command: 

. R LINK 
* 

(‘♦' indicates that the Linker is waiting for a command.) 

The first command line can include the output file, a map file if desired, and up to six input files. 
The file PASCAL.OBJ, which contains the Pascal run-time library, must be used when linking a 
Pascal program. The example below links the object module MAIN with two others, SUB1 and LIB1, 
to produce a “privileged* MAIN.SAV file and a MAIN.MAP file. The job is privileged in that the 
monitor, device handlers and I/O page are mapped into the program's address space, as opposed to 
being excluded from the program’s memory (a “virtual* job, see below). 

♦ MAIN ■ MAIN=MAIN. SUB1, LIB1 /C 

♦ SY:PASCAL 

♦^C 

An alternative to the R LINK command is LINK. LINK, a DCL command, allows you to enter the 
command line on the same line as the command, as in: 

. LINK MAIN.SUB1.LIB1.SY:PASCAL 


Virtual Jobs and the XM Monitor 

The XM monitor has the ability to create a “virtual job* with a separate 32K word address space. 
A virtual job does not need to reserve space for the monitor, device handlers, or the I/O page, and 
can therefore use the entire available address space. A virtual job cannot make direct reference to 
device registers or perform other specialized functions. These operations are restricted to “privileged 
jobs.* For most purposes, virtual jobs are preferred. 

Making a virtual job requires the setting of bit 10 (2000 octal) in the JSW (Job Status Word) in 
location 44 (octal) of the .SAV image file. The file VIRJOB.OBJ, supplied with Pascal-2, sets the 
virtual bit in the JSW for Pascal-2 or other programs. VTRJOB should be included as an input file 
in the Linker command(s). 

. R LINK 

♦ MAIN = MAIN,SUB1,LIB1,VIRJOB/C 

♦ SY:PASCAL 

♦IC 

One additional restriction: The .SAV image file containing a virtual job must be stored on the system 
device (SY:), and must be run via the R command. 
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Overlays 

Overlaying is the method of dividing a program logically into small pieces called “segments,” allowing 
you to execute a program that is larger than the available memory (32K). Each overlaid program has 
a root segment that is always resident in memory and any number of executing overlay segments. 
Each segment is assigned to a particular area of memory called an overlay region, with each overlay 
region containing one or more segments. 

A program may require (further) overlaying if run-time errors such as “not enough memory” or 
“stack overflow” cause the program to abort, or when the program cannot be loaded into memory 
because it is too large. 

The Linker is capable of creating two kinds of overlay structures, low memory overlays on the 
SJ, FB and XM monitors and extended memory or “virtual” overlays on XM. With low memory 
overlays, only the root and the executing segment reside in the program’s 32K address space; all other 
segments reside on disk and are called in and overlaid against the previous segment, overwriting it. 
Extended memory overlays require the extended-memory features of the XM monitor to create a 
physical address space greater than 32K words for the program. This address space is made up of 
segments assigned to specific virtual overlay regions. Once called into virtual memory to execute, 
a virtual overlay region remains in physical memory, thus reducing the number of disk accesses to 
load in the next segment. 

In most cases, low memory and extended memory overlays may be mixed for added program 
flexibility. Details of both types of overlays are given below, oriented toward Pascal tasks. The full 
overlay capabilities are described in the RT-II System Utilities Manual. 

NOTE 

The Linker uses channel 15 as the overlay load channel; for this reason, your 
program should not access channel 15 directly. See the “Support Library” 
section for information on channels. 

Low Memory Overlays 

The /G:n (Low Memory Overlay) option selects the low memory overlay facilities of the Linker, 
where the parameter n indicates the overlay region number. Sets of modules allocated to the same 
region will be overlaid against other modules in the same region, with only one set of modules per 
region actually in memory at any one time. 

The following sequence links a main program and several external modules into an overlaid executable 
file. The main program and the Pascal library are not overlaid and must be in the root segment (on 
the first command line). FIRSTA and FIRSTB do not call each other and are overlaid against each 
other in region 1. TIOA and TWGB do not call each other and are overlaid against each other in region 
2. The set of NEXTA, NEXT2A, and NEXT3A are overlaid against the set of NEXTB, NEXT2B, and NEXT3B 
in region 3. No module in one set calls a module in the other set that is overlaid in region 3. The 
continue option (/C) allows the input file list on the next line to be included in the linking. 

. R LINK 

♦ PROG = MAIN.SY:PASCAL/C 

♦ FIRSTA/0:1/C 

♦ FIRSTB/0:1/C 

♦ TWOA/Q:2/C 

♦ TWQB/0:2/C 

♦ NEXTA.NEXT2A,NEXT3A/0:3/C 

♦ NEXTB.NEXT2B,NEXT3B/0:3 

♦:c 


2-16 


















The Linker, Overlays, and the Librarian 


You can also use the command LINK/PROMPT, with the same effect. 

Extended Memory Overlays 

The /V:n:m (Extended Memory Overlay) Linker option is used to create extended memory overlays 
where n is the overlay region number and m is the optional partition into which the segment is loaded. 
Both privileged and virtual jobs can use extended memory overlays. The /V:n:m option produces 
a load image that no longer requires the I/O page and monitor to reside in the program’s address 
space. This makes the entire address space available to the program, an advantage for programs 
with large root segments or with high demand for dynamic memory (stack and heap). 

The next example uses the same program files as in the preceding overlay example to create a virtual 
job. Note that the /V:n:m option replaces the /0:n option used above. 

In addition to the main program and support library, the root contains the VIRJOB code, making 
the program a virtual job. For comparison, refer to the example in the next section in which the 
root is a null segment and the main program and support library are loaded into the first (and only) 
virtual overlay region. 

. R LINK 

♦ PROG = MAIN.VIRJOB.SY:PASCAL/C 

♦ FIRSTA/V:1/C 

♦ FIRSTB/V:1/C 

♦ TWQA/V:2/C 

♦ TWOB/V:2/C 

♦ NEXTA.NEXT2A.NEXT3A/V:3/C 

♦ NEXTB,NEXT2B,NEXT3B/V:3 

*IC 

Linking a Program Whose Root Exceeds 10K 

Due to a restriction in the XM monitor, Pascal programs with root segments or mainlines larger than 
16K words cannot be loaded at all. This restriction applies to both privileged and virtual jobs. In the 
case when overlaying, or further overlaying, of the program is undesirable, use the file START.OBJ 
from the Pascal support library to create a “null* root segment. This places the program code in 
the first (and only) virtual overlay region. In the process excess memory in the root is added to the 
heap’s free list, increasing the amount of dynamic memory available to the program. 

START contains code necessary to create a null root. START defines two “grow* psects, P$GRGI 
and P$GRUH, which are used in the creation of the 4K-word null root segment containing low core 
and vector information (lOOOg words) and START (32 words). 

The /U: 20000 (Round) Linker option expands P$GR0W to the root’s upper boundary (P$GRUH). At 
run time, the Pascal support library places this excess region on the heap’s free list for use by the 
Pascal program. 

When START is used, any number of segments but only one virtual overlay region can be specified 
in the overlay structure. Programs having more than one virtual overlay region cannot be linked 
in this way. As the next example shows, each overlaid module is placed in its own partition within 
the virtual overlay region. The overlaid module is loaded into virtual memory when first called and 
resides there for the remainder of the execution, reducing the number of disk accesses. The V:l:l 
option creates virtual overlay region 1, partition 1, containing the tables and code for program TEST 
and the Pascal support library. The START and VIRJOB code is placed in the root. 
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Example: 

. R LINK 

♦ TEST = START.VIRJDB/U:20000/C 

♦ TEST.SY:PASCAL/V:1/C 

♦ FIRSTA/V:1:2/C 

♦ FIRSTB/V:1:2/C 

♦ TWOA/V:1:3/C 

♦ TIQB/V:1:3/C 

♦ NEXTA. NEXT2A. NEXT3A/V: 1:4/C 

♦ NEXTB.NEXT2B.NEXT3B/V:1:4/C 

*LL 

Round section? P$GR0T 
♦^C 

For more information on virtual jobs and overlays, see the RT-11 Software Support Manual and the 
RT-11 System Utilities Manual . 

The Librarian 

The Librarian combines relocatable object module files to form an object module library. This library 
may be included as input to the Linker, which will select only those modules needed by the program 
being linked. Note that a module always consists of the entire set of procedures and functions from 
its compilation. Individual procedures cannot be selected from a module. 

For example, the dynamic string package STRING.PAS, supplied as a Pascal-2 utility, can be edited 
to form 12 files, with each file containing one procedure or function. The 12 files can then be compiled 
and combined into a library containing 12 modules, as follows. 

. R LIBR 

♦ STRING=LEN.CLEAR.READS.WRITES.CDNC,SEARCH/C 

♦ INSERT,ASSIGN,ASCHAR,EQUAL.DELETE,SUBS 

♦ ~C 


Extended Precision 


Values of type real are normally stored in the PDP-11 single-precision format, which requires 2 
words of storage per value and offers about 7 decimal digits of precision. The double compilation 
switch or the $double embedded switch gives double precision to all real values. Each extended- 
precision value occupies 4 words of storage and provides approximately 15-digit precision in all real 
calculations, including the transcendental functions. 

Normal and extended-precision values cannot be mixed in a program: the double or $double switch 
generates extended precision for all real values. All external modules must be compiled with the 
same precision as the main program, even if no real variables are present. 


In addition, you must use the colon notation output format (e.g., E: 18:16) to display double 
values in write statements. 


precision 
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Support Library 


The Pascal support library is a collection of modules contained in an object module library called 
PASCAL.OB J located on the system device. When compiling a program, the Pascal compiler generates 
subroutine calls to routines in the Pascal support library. The Linker places these routines in 
the run-time library. The entry points in the library are identified as pinna where ana is a small 
integer. Appendix E of this guide contains a list of these support library entry points. To see 
these subroutine calls, inspect the MACRO-11 code generated by the Pascal-2 aacro switch. Support 
library routines not called by the compiler have a name instead of a number following the p|. 

Most of the routines in the Pascal support library perform I/O operations or arithmetic computations 
such as floating-point simulation or trigonmetric function approximation. Other routines allocate 
dynamic memory and report error conditions. Still other routines allow you to change the run-time 
error reporting to suit your needs. When you build a Pascal job, the Linker searches the Pascal 
support library for the modules required to run the job. For example, if you compute a logarithm in 
your program, the Linker includes the support library module that approximates logarithms (IFLOQ, 
which defines the entry point p$102). 

In most Pascal tasks, the Linker includes from 3K words to OK words of library modules. 
Initialising the Support Library 

The Pascal support library is initialised at the start of a Pascal program. When a typical execution 
begins, the system transfers control to plbga, the transfer address of the program, and the support 
library initialization procedure p|50 is called. This procedure initializes global variables used by the 
support library; then it requests that the operating system expand the program code by 4K bytes 
to make room for the stack, which is originally located in low memory. The routine then moves the 
stack from low memory to its new location at the end of the program code. 

After the stack is repositioned, control transfers to p$33, the file initialisation routine. P|33 assigns 
the standard files laput and output (channel 16 and 17 for both) to TT:, the terminal. (Channels are 
discussed below.) The support library then transfers control to the first statement of the program, 
and execution begins. However, if the program is being debugged with the Debugger, instead of 
control transferring to the program, control transfers to p$67, the Debugger initialization routine. 
This routine initializes the Debugger and opens its files. The Debugger then takes over execution of 
the program. (See the Debugger Guide for details.) 


Support Library Data Definitions 

Constants, data and internal file definitions used by the support library are contained in the file 
LIBDEF.PAS, included in the Pascal-2 distribution kit. In addition to its use with the support 
library, this file is “included” in the error-reporting module OPERRO.PAS. LIBDEF defines the file 
variable, the file status block and the library data area. 

By using the Slaclude directive, users can include LIBDEF PAS in any program that accesses the 
support library's work area directly. The example program PCHAN.PAS, below, defines a function 
named GetChaanel, which returns the channel number associated with an open file. The program 
prints the channel numbers for standard files input and output and for two other files opened by the 
program. Note that the support library stores the channel number times 2 because RSTS requires all 
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channel numbers be doubled. Also noteworthy is the fnnctioe loophole, predefined in the compiler 
and used in GetChaaael. See the Language Specification for details on loophole. 

prograa PrlatChaanel; 

(Include 'libdef'; 
coast 

Firstflle ■ 'FILE1.DAT 1 ; 
rar 

Z, T: text; 

Fileaaae: packed array [1..10] of char; 

function GetChaaael(rar I: teat): integer; 
rar 

F: aser.flle.rariable; - data type defined in LIBDEF PAS 

begin < procedure GetChaaael > 

F :* loophole(aser.file.rariable,I); 

GetChaaael :» F*.chaaa«.\ dir 2; < RSIS uses chaaael • 2 > 

end; < procedure GetChaaael > 

begin < prograa PrlatChaanel > 
writelaOInput is open on chaanel: *, GetChaanel(input)); 
wrifcelaOOutput is open on chaaael: GetChaaael(output)); 

rewrite(X,Firstflle); 

writela('File 1, Firstflle,', is open on chaaael: GetChaaael(X)); 

write('Enter a file anas: ’); 
readln(Fileaaae); 
reset(T,Fileaaae); 

writelaCFile 2, ’.Fileaaae,’, is open on chaaael: *, GetChaaael(D); 
end. { prograa PrlatChaanel > 

To compile and execute the program, use this command: 

B PASCAL 
♦ PCHAI 

■ B Lire 

•f < ?H AI=P<?BAli ST; PASCAL 

■ BOX PCHAl 

Input is open oa chaaael: 10 

Output is open oa chaaael: 17 

File 1, FILE1.DAT, is open oa chaanel: 16 

Eater a file aaas: FILE2.DAT 

File 2, FILE2.DAT, is open oa chaaael: 14 


NOTE 

The definitions in LIBDEF.PAS are prorided for informational purposes 
and are subject to change with each release of Pascal-2. Users who desire 
a more detailed description of the internal workings of the Pascal support 
library must obtain the library sources. 


/r- 

^2 


Updated January 198* 
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Support Library’s Use of Channels 

An I/O channel is the means by which RT-11 and the Pascal support library coordinate access to 
files opened via reset or rewrite. Channels are numbered 0 through 15 (decimal), which means 
a Pascal program can have up to 16 files opened at one time. If the program is overlaid, however, 
RT-11 reserves channel 15 as the overlay load channel, which is then unavailable for use by the 
program. For overlaid programs, up to 15 files may be open at the same time. 

Normally, Pascal users do not need to know which channels are associated which files in their 
program; all file accessing is handled automatically by the Pascal support library. However, in some 
special applications, the channel assignments may be important. For example, a user wishing to open 
a file from Pascal and access the file with specialized MACRO-11 subroutines needs to make sure 
the same channel is accessed from Pascal and from MACRO-11. 

As the preceding example program PCHAN.PAS shows, input is associated with channel 16 and 
output with channel 17. These channels are not true channels because actual I/O transfers are made 
through .TTYIN and .TTYOUT system calls, which do not require channels. They are assigned to 
input and output so the support library can reference all open files by channel number. 

The preceding example program also shows the order in which the Pascal support library allocates 
channels, from high to low (channel 15 down to ch ann el 0). 

If you use reset or rewrite on the standard files input or output, or if you allocate another file 
variable to TT: (the console terminal), the support library assigns a channel from its own list of 
available channels. 


NOTE 

Because the support library maintains its own list of available channels, it 
does not use RT-11 system library routines to get the next free channel. 
Conflicts in channel allocation arise when a Pascal program calls MACRO- 
11 external modules that open a file on a specific channel and then attempts 
to open a file on the same channel. 


When a file is closed, the channel associated with the file is place on the list of channels available to 
the program. 


2-21 






Pascal-2 V2.1/RT-11 Programmer’s Guide 


Run-Time Organization 


Form of the Generated Code 

Pascal-2 code is divided into program sections called “psects.* The psects for the main program 
and any separately compiled procedures are combined with the Pascal support library by the Linker 
to produce an executable program image. The use of multiple psects arranged in the order the 
Linker encounters them provides greater flexibility for the combination of individual procedures into 
a program. (The “blank* psect is normally placed first.) 

The compiler generates these psects: 

“blank* The instruction code for the compilation unit. The blank psects for all compilation 
units are concatenated; compiled code will not attempt to write to this psect. 

CQNSTS Contains all constants generated by the compiler. This includes constants declared 
by constant declarations or implicit in the code. This psect also contains jump tables 
generated by case statements, so there is a complete separation of instruction references 
and data references. The CONSTS psects for all compilation units are concatenated; 
compiled code will not attempt to write to this psect. 

DIAGS Contains line number and procedure name data used in the printing of the run-time 
walkback. The information is encoded to save space. This psect is not generated if the 
nowalkback switch is specified in the compilation. 

GLOBAL Contains all global variables used in the main program and external procedures. This 
psect is arranged so that the global variables are shared among all procedures. The 
main program and all procedures that reference global variables should have exactly 
the same declarations. The size of the resulting psect is that of the largest GLOBAL 
psect generated by any of the compilation units. 

If the own switch is specified in the compilation, this psect is instead named with the 
first six characters of the program name, allowing multiple global variable segments. 
Compiled code will write to this psect. 

P$DYNL A two-word psect defining a dynamic link to the Post-Mortem Analyzer. (The PMA 
prints the walkback.) The first word of the psect is a pointer used by the PMA to trace 
the stack frames for the walkback. With walkback enabled, the second word of this 
psect contains the address of P$PMA, the entry point of the PMA. If the nowalkback 
or nomain compilation switch is used, the second word contains a zero and no jump is 
made to the PMA. 

SHIFTS Generated only if the target machine does not have the EIS hardware option (sim). 

This psect contains a table of shift instructions that simulate multiple shifts. The psect 
is overlaid in a manner similar to TABLES and is treated as read-only by the compiled 
code. 

TABLES Contains bit tables used for access to set elements and individual bits within a word. All 
Pascal compilations generate this psect, but all copies will be overlaid by the Linker so 
that only a single copy will exist in the final program. Compiled code will not attempt 
to write to this psect. 

The following table summarizes the attributes of the various psects. Refer to the MACRO-11 manual 
for further information on the meaning of the attributes. 
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Psect Name Attributes 


“blank* 

CONSTS 

DIAGS 

GLOBAL 

P$DYNL 

SHIFTS 

TABLES 


RI,I,LCL.REL.CON 
RI, D,LCL,REL,CON 
RI, D,LCL ,REL,CON 
Rf,D,GBL,REL , OVR 
RI,D,GBL,REL,QVR 
RI.I,GBL,REL,OVR 
RV,D,GBL,REL,OVR 


So that Pascal programs may be included in libraries, each Pascal-2 object file has a module name 
consisting of the first six characters of the output file name. Thus a program compiled with the line: 

. R PASCAL 

♦ RESPROG = HDR.INPRQG 

will have the module name RESPRO.OBJ. This compilation performs “source concatenation.* Note 
that with source concatenation INPROG.PAS must not contain a program statement or compilation 
errors will result. 


Memory Organization 

On the PDP-11 a program has access to 32768 words (frequently abbreviated to 32K). The exact 
arrangement of storage is determined by the commands to the Linker, but a typical program may 
look something like Figure 2-1, which represents a snapshot taken during execution. The numbers 
are representative; actual values vary from program to program. 

RT-11 System Area 

The RT-11 System Area occupies the first 256 words of all programs and contains interrupt vectors 
and status indicators used by RT-11. This area is also used for communication between the Pascal 
program and other programs linked by chaining. 

Program Code 

The program code section contains the instructions for the user program. The size of this section is 
determined by the amount of user code. 

Global Variables 

The global variables section contains the global variables used by the Pascal main program and 
external procedures. The size is that of the largest global variable section in any compilation unit. 

Constants 

The constants section consists of all constants, such as strings or real constants, needed by the 
program. The section also contains the jump tables for case statements. The size of this section is 
determined by the user code. 

Tables 

The tables section, which contains data needed by all Pascal programs, is 40 bytes long. 

Run-Time Library 

This section contains routines from the Pascal run-time library used by a program. Only those 
routines needed by a particular program are loaded here. 
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I/O Page 


RT-11 monitor 


-stack- 

USR swap area 


heap 


run-time library 


tables 


constants 


global variables 


program code 


RT-11 System Area 


32K 


28K 

26K 

-SP 


16K 

14K 

10K 


Figure 2-1. Typical Memory Layout of a Pascal Program. 


The Stack 

The stack contains all variables local to inner blocks of the program, plus parameters, procedure 
linkage information, and temporary working storage. Upon entry to a procedure or function, space 
is allocated on the stack (a stack frame) containing space for all storage local to that block. The 
format of the stack frame is described below. 

The stack starts at the highest available address and expands downward, and the heap begins just 
after the program image and grows upward. This allows the maximum room for growth in both. 

The stack pointer (SP) always points to the top of the stack (lowest physical space). If the space 
available for the stack is too small, the stack pointer will eventually exceed the limits of the stack 
space and cause the “stack overflow” error. 

The Heap 

The heap is an area for dynamically allocated memory used for I/O control blocks, buffers, and 
variables allocated with new. 

The heap is allocated from the bottom of available memory and can grow until it meets the stack, 
which is allocated at the top of available memory. 

Space is returned to the heap when files are closed or when variables previously allocated with the 
standard procedure new are deallocated with the standard procedure dispose. Such space is then 
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Run-Time Organization 


available for further heap allocation. The error message “not enough memory* results if no space is 
available to satisfy a request for heap storage. 

If a program running under XM is linked as a virtual overlay job, the overlays can be structured in 
such a way that the excess (and unused) space in the null root is added to the heap’s “free list* of 
available memory. See “The Linker, Overlays, and the Librarian" for details. 

For information on ways to monitor the allocation of the stack and heap at run-time, refer to the 
section on “Monitoring Memory Usage” later in this guide. 

The Monitor and I/O Page 

For RT-11 systems other than XM virtual jobs, the monitor space contains the RT-11 resident 
monitor, the user service routine (USR) if it is set “NOSIAP," and any device handlers loaded with 
the LOAD command. The I/O page contains device status and command registers. 

For an RT-11 XM virtual job (bit 10 set in the JSW), the monitor and I/O page are not allocated, 
and the stack will begin at the top of user memory. See “Virtual Jobs and the XM Monitor” for 
details. 


The Stack Frame 


As each procedure or function is entered, space is allocated on the stack for parameters, linkage 
data, and local use. This space is called a “stack frame”; the “stack” consists of these stack frames. 

Figure 2-2 shows the format of a stack frame. 


(previous stack frames) 


function return value 

parameters 

return link 

dynamic link 

local variables 

register save area 

temporary storage 



Figure 2-2* Format of a Stack Frame* 


Not all of the fields will be used by the compiler for every procedure; only the return link is present 
in every frame. It is the responsibility of the called procedure to remove the parameters and local 
variables from the stack before a return is made to the caller. 
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Function Return Value 


The function return value field appears only for functions. A value assigned to the function name 
within the function will be stored in this location and left on the top of the stack when the function 
returns. Space for this field is allocated by the calling routine before evaluation of the arguments 
for the function call. The space is removed from the stack when the calling routine has no further 
use for the value. 

Parameters 


The parameter area has an entry for each parameter to the procedure or function. The entry for a 
value parameter will contain the value of the corresponding argument, while the entry for a variable 
parameter will contain the address of the argument. Parameters are pushed onto the stack as they 
are evaluated, in left to right order, so the first parameter to a procedure will be the first one pushed 
onto the stack. 


Return Link 


The return link is the address to which control will be transferred on return from the procedure or 
function. 


Dynamic Link 

By default, procedures compiled with valkback enabled establish a dynamic link that points to the 
dynamic link in the previous stack frame. The base of the linked list of stack frames is contained 
in the first word of the psect P$DYNL. When a run-time error is detected, the dynamic link is used 
to show the procedure calls that led to the error (the procedure walkback). A dynamic link is not 
present in the stack frame for procedures compiled with nowalkback. 


Local Variables 

The local variable field contains space for all local variables of the procedure or function. The field 
is allocated upon entry to the block. 

Register Save Area 


This area saves the values of all registers used within the procedure. The registers are saved on entry 
to the procedure and restored on exit. Only registers actually used are saved. The general registers 
are stored first, with the highest register used pushed first. (This is important to the algorithm for 
locating variables in lexically enclosing blocks.) 


Temporary Storage 

In the process of generating code, expressions that are used more than once are computed and the 
values saved. These values may be saved on the stack if no register is available to hold them. Also, 
the stack is used to interface with support library routines and the operating system. 
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Monitoring Memory Usage 

An executable Pascal program is typically arranged in memory with the program code written to 
low memory, followed by the memory area shared by the stack and heap. The I/O page and monitor 
are loaded into the high end of memory. (In this discussion, a typical Pascal program uses no Linker 
options to rearrange memory.) The remaining memory is unallocated and available for the stack 
and heap. 

To arrive at this arrangement, the following events occur: 

1. The program code is loaded into memory, with the stack in low memory. 

2. The support library initialization procedure is called, initializing the support library and per¬ 
forming the next three steps. (See the “Support Library” section.) 

3. The stack is moved to its new location at the highest available memory location with the 
.SETTOP -2 directive or at the address specified on the /M:n Linker option. 

4. P$KGRE, the pointer to the top of the heap, is initialized. The heap immediately follows the 
program code. 

5. The user program is started. During execution, if the stack and heap meet, the program 
terminates with either of two errors, “not enough memory” or “stack overflow,” depending 
on the cause. 

Although overlaid programs differ from non-overlaid programs in their arrangement in memory, 
the same sequence of events occur to load them into memory. In this case, the program code is 
made up of a root segment and a number of overlay regions into which the progam is divided at 
link-time. For low memory overlays, if the heap is exhausted, no more memory is available and the 
program terminates. For extended memory overlays (virtual overlays), the excess memory in the root 
segment is placed on the heap’s free list, extending the memory available for the heap. This and 
other information on overlays is described in “The Linker, Overlays, and the Librarian” and later 
in this section. 

In certain applications you may find it advantageous to keep track of the stack and heap as they 
are used by a program. The Pascal support library contains three routines — space, p$inew and 
pidispose — that allow you to keep track of memory allocated to*the stack and heap. Briefly, the 
space function returns the amount of stack and heap space available to an executing program at a 
particular time. The p$inew function returns the address of a block of memory having a specified 
length. The p$dispose procedure deallocates blocks of memory allocated by p$inew. In a later 
example a boolean function NewOK is provided, which not only shows the correct way to use the 
three routines but also is useful in determining whether enough memory is available to satisfy a 
request for a block of memory. 

Two reasons for monitoring the size of the stack and heap are to find out how close the program 
is to running out of memory, and to find out whether enough memory is available to perform a 
given subtask. For example, a checkers-playing program could use these functions (as in NewOK) to 
determine the number of moves that the program can look ahead based on the amount of memory 
available to perform the look-ahead. 

Space can be called independent of the other two support library routines, whereas p$dispose must 
be used to deallocate memory allocated by p$inew. The routines are described in detail below. 
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The 4 Space’ Function 

The space function is used to determine the amount of stack and heap space available to an executing 
program. With this function you can determine how close the program is to running out of memory. 

The function space must be declared external to the program, as shown: 

function Space: functype; external; 

where functype is the data type of the function and its returned value. The function is usually 
declared of type integer but another data type similar to integer, “unsigned” (0. .66535), can be 
used to represent the value. The value returned by space depends on the amount of space allocated 
to the stack and heap. 

Figure 2-3 is a memory diagram showing a program’s arrangement in memory and its allocation of 
stack and heap space. The diagram also shows the relationship between the stack and heap and the 
returned value of the space function. This diagram is designed as an aid in visualizing the use of 
the stack and heap and as an aid in understanding the way the value of space is arrived at. 

As is the case on RT-11, the stack and heap share the same block of memory. The stack begins at 
the high end of the stack/heap area and grows down; the heap begins at P$K0RE, the low end of 
the block and grows up. The space function monitors the use of the sjack and heap, returning the 
difference between the top of the stack (SP) and the top of the heap (P$K0RE). 

The figure is divided into “times,” or snapshots of a program in memory at various stages of its 
execution. Time 0 is the point at which the user program actually begins execution, after the program 
code is loaded into memory and the support library is initialized. 

The figure contains the following five symbols. Curled braces designate the value that the space 
function would return at the indicated time. Vertical arrows represent stack and heap expansion. 
SP signifies the stack pointer. P$K0RE is a pointer to the top of the heap. In general, KB stands for 
K bytes; 64KB stands for 64K bytes or 32K words, the high end of memory; 56KB stands for 56K 
bytes or 28K words, the end of the RT-11 monitor and beginning of the I/O page; 52KB stands for 
52K bytes or 26K words, the bottom of the stack and the beginning of the monitor; 0KB denotes the 
beginning of memory (low core and vectors).. These memory locations are typical of Pascal programs 
but may vary from program to program. 

Be aware of the fact that the space function does not account for the fragmentation of the heap as 
a result of calls to new and dispose and the opening and closing of files. Unused portions between 
the low and high end of the heap are treated as if they are allocated. Again, for extended memory 
overlays the space function does not take into account the memory added to the heap’s free list. 

See the example under “Example: Function NewOK” for use of space. 

Function 4 P$inew’ and Procedure 4 P$dispose’ 

The function p$inew and procedure p$dispose are entry points for the standard procedures new and 
dispose. P$inew allocates a specific sized block of memory, and p$dispose deallocates a specific 
block. As a comparison, the standard procedures new and dispose determine the size of the block 
to allocate or deallocate from the length of the data type. 

An example use of p$inew and p$dispose is a cache system in which a program needs to use as 
much memory as is available for data storage before it writes the data to a file. 
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Figure 3-3. Tracking Memory Usage with the SPACE function. 

At Time 0, the support library has been initialized bat no Pascal statements bare been executed. 
The stack and heap, in sharing the same block of memory, grow toward each other and ideally 
never meet. If space is called at Time 0, the value it returns is equal to the size of the stack 
and heap area (SP minus PtKORE/. At Time 1, the amount of stack and heap remaining and 
the value of a pace, being identical, both decrease by the same amount as stack and heap space 
is allocated. As time progresses, memory available for the stack and heap continues to be used 
and disposed of until the program ends or until the allotted memory is exhausted and the 
program aborts. 


Defined in the support library, these two routines must be declared external to the program, as 
shown: 

function P$inee( blocksize: argtype): functype; external; 
procedure Ptdlspose (pointer, blocksize: argtype); external; 


where 

blocksize is the size of the memory block to be allocated or deallocated, in bytes, 
pointer is the address of block to deallocate. 
argtype is the data type describing size and pointer. 

functype is the data type of the function’s return value. The returned value is the address of the 
block. If there is not enough contiguous memory available to satisfy the request, a value 
of 0 is returned for numeric data types, all for pointer types. The most common types 
used with ptlnev and ptdlspose are the standard type Integer and a user-defined 
type unsigned, in the range 0..65535. 

For an example showing the use of ptlaev and ptdlspose see the code for procedure levOK, below. 
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Exmmplet Function ’NewOK’ 

The boolean function InuOK, provided below as an external, uses the three routines previously 
described functions to determine whether a block of memory can be allocated, leaving a specified 
amount of stack space. We recommend that yon reserve 200* to 1000* bytes of stack space for 
parameter and local variable storage and for error processing. The amount of memory you reserve 
depends on the parameter and local variable requirements of the procedures being called by the 
program. For instance, if the program calls numerous procedures, each containing a large number 
of parameters and local variables, the amount of memory to reserve would be greater than for a 
program that uses smaller procedures. 


NOTE 

If a program that uses InuOK aborts with a “stack overflow” error, the amount 
of reserved memory is probably not large enough for the amount of stack space 
required for parameters and local variables. To alleviate this error, increase the 
amount of memory you are reserving for the stack. 


In addition to showing the correct way to use the three routines, leuOK can be incorporated into 
your programs when you need to determine if a request for memory will fail. 

leuOK, which could be stored in NEWOK.PAS, returns a trun value if the block can be allocated, 
falnn if the block cannot be allocated. The first argument to InuOK is the size, in bytes, of the 
memory to be allocated. Use the six# function to determine the size of a Pascal data type. (The 
•iza function is described in the Language Specification.) The second argument is the amount of 
stack space in bytes that you want to remain unallocated, if the block is allocated. 

First, the function allocates the desired block of memory with the call to plineu. If plinau returns 
a zero, this means that there was not enough memory available to allocate a block of that size, and 
InuOK returns false. However, just because the block was allocated does not necessarily mean that 
InuOK returns trun. If the returned value of space is less than the amount of stack space you have 
reserved for variables, etc., InuOK is set to false because memory would be taken from the reserved 
block. Of course, the function returns a true value if the block was safely available. Finally, the 
same block of memory is disposed of by pldlsposn. (Remember, InuOK only checks to see if a block 
of memory could be allocated. To allocate the block, call sou.) 

(Inoaain) 

typo 

Unsigned = 0..66635; { Unsigned integer > 

function plineu(Blocksizn: Unsigned): Unsigned; 
external; { Allocate a specific sized block of aeaory > 

procedure pldlsposn(Pointer, Blocksizn: Unsigned); 
external; < Dispose of a specific sized block of aeaory > 

function space: Unsigned; 

external; { Determine aaouat of stack space left ) 


Updated January 1085 
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function Nevok(Reserved, Stackspace: Unsigned): boolean; external; 

{ Check if block of size “Reserved* can be allocated leading H Stackspace M > 

function NevOk; 


P: Unsigned; { Address of block if allocated > 

begin { NevOK > 

P := p$inev(Reserved); 
if P = 0 then NevGK := false 
else 
begin 

NevGK := space >= Stackspace; 
p$dispose(P, Reserved); 
end; 

end; { NevOK > 

To show the correct way to set up the critical variables and call NevOK, a checkers-playing program 
could use NevOK to find out how many moves it can look ahead. The sample program provided below 
does just that. For illustrative purposes, the program, CHECKT.PAS, simulates a real checkers 
program, making use of a 10,000-word array Dum to produce a larger task size. CHECKT uses a 
linked list to store the, look-ahead moves a normal checkers program would make. The program 
merely illustrates the use of NevOK to perform the look-ahead. 

program Cheekiest; 


{ Try to allocate block > 
{ No luck > 


{ Check for enough stack left > 
{ Deallocate the block > 


const 

Reserved = 200; { amount of stack space to reserve > 


type 

Unsigned « 0..65535; 

Ptr = -Node; { 

Node = record { 

Father: Ptr; { 

Son: Ptr; { 

Brother: Ptr; < 

Value: integer; { 

Move: integer; { 

Jumpl, Jump2: integer; { 
Mobility: integer; { 

Attack: integer; { 

Gradient: integer; < 

Bits: integer; { 

end; 


Pointers into search tree > 

Node in search tree > 

Father of this node > 

Pointer to best son > 

Link to next brother > 

Value of this board position > 
Move descriptor to reach node > 
Jumped pieces removed by move > 
Mobil and deny > 

Pin and threat > 

Target gradient > 

Scoring bits > 


var 

Alloc: boolean; 

P: Ptr; 

Movesize: unsigned; 

NumMoves: unsigned; { number of moves > 

Nextmove: node; 

Dum: array [1.. 10000] of integer; { Dummy array simulating a long program > 
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function NewOK(Reserved, Stackspace: Unsigned): boolean; 
external; 

i Check if block of size “Reserred" can be allocated learing ■ Stackspace■ > 

begin { Cheekiest > 

Moresize : = size(Node); 

write In (‘The size of amove is: 1 , Moresize :1) ; 
new(P); 

NumMores := 1; 
repeat 

al loc : = Newok (Moresize, Ee serred) ; 
if alloc then begin 
new(P".son); 

P := P~.son; 

NumMoves := NumMores + 1 
end; 

until not alloc; 

write('The number of mores necessary to fill up the heap is: *); 
writeIn(NumMores:1); 
end. { Cheekiest > 

The compilation process for this program is as follows: 

. R PASCAL 
♦ NEWOK 
. R PASCAL 
♦CHECKT 

. LINK CHECKT=CHECKT,NEWOK,SY:PASCAL 

. RUN CHECKT 

The size of a more is: 22 

The number of mores necessary to fill up the heap is: 1141 
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Storage Allocation 

The compiler assigns storage for variables of pre-declared types as shown in this table: 


Type Siie (bytes) Alignment (bytes) 


Boolean 

i 

1 

Char 

i 

1 

Integer 

2 

2 

Real 

4 

2 (Idouble off) 

Real 

8 

2 (fdouble on) 

Text 

2 

2 

Space for user-defined types is allocated as follows: 



Enumeration 

If the type has up to 256 members, it is allocated one byte aligned on a byte boun¬ 
dary. If it has more than 256 members, it is allocated two bytes, aligned on a two- 
byte boundary. 


Subrange 

Allocated in the same way as the parent type. 

Pointer Allocated two bytes, aligned on a two-byte boundary. 

Array Allocated the amount of space needed to hold the number of elements specified, aligned 
in the same way as the element type. The elements are placed in ascending memory 
locations. 

Set Allocated one bit for each member of the base type, with the total size rounded up 

to the next larger full byte. Bit allocation begins with the least significant bit of the 
first byte. If the size is a single byte, it is aligned on a byte boundary; otherwise it is 
aligned on a two-byte boundary. A base type that is a subrange is expanded to the 
full range of possible values before the set is allocated. For example: 

type 

Color = (Red, Orange, Yellov, Green, Blue); 

Hot = Red..Yellow; 


Colorset = set of Color; 

Hotset = set of Hot; 

In this example, Hotset is allocated the same amount of space as Colorset. A maxi¬ 
mum of 256 members is allowed; a base type of integer, or any integer subrange, has 
members from 0 to 255. 

Record Each field in the record is allocated space in the same way as a variable of the same type, 
in the order specified. The alignment of the record is the maximum of the alignments 
of its fields. 


Packed Array 

The number of bits needed to contain each element is computed. For example, the sub¬ 
range type 0.. 3 requires two bits to contain a value. If the space required for an element 
is less than a word, the element size is increased to the smallest power of two bits (1, 
2, 4, 8, 16) that will contain the value. The array is allocated space to hold the number 
of elements specified, where each element is considered to be of the size just computed. 
If elements are allocated eight bits or less, the array is aligned on a byte boundary. 
If the elements require a word or more, space is allocated as for a normal array type. 
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Packed Set 

The same as unpacked sets, except that the size is not rounded up to an even byte 
and the alignment is to a byte boundary. 

Packed Record 

Each field in the record is allocated exactly the number of bits required to con¬ 
tain it, except that a field of a simple type that would span or cross a word boun¬ 
dary will be forced to begin at a word boundary. Fields are allocated in the or¬ 
der declared, beginning at bit zero (least significant bit). 

NOTE 

The predefined functions size and bitsize will report the amount of 
storage allocated to any user-defined structured type. See the Language 
Specification for details. 
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Run-Time Error Reporting 

The Pascal-2 run-time error reporting system is intended to simplify error analysis by reporting 
run-time errors in terms of source lines and procedure names. Upon detecting a run-time error, the 
reporting system prints a short description of the error, then traces the execution history, procedure 
by procedure, from the point of error back to the main program. This is called a “walkback,” or 
“traceback.” 

Err ora are detected by the hardware or by special checks inserted in the generated code. After an 
error is detected, control of the program then passes to an error routine, which closes all open files 
and prints an error message and stack traceback. 

The walkback consists of the following: 

• The message header, which includes the program name, type of error, and program counter 
at the time of the error. The two types of run-time errors are “fatal” and “I/O.” Fatal errors 
are unrecoverable; I/O errors are recoverable. For details on I/O-error recovery, see “I/O Error 
Trapping” later in this section. The program counter is the location at which the error occurred. 
If you utilize the walkback, the program counter is of little use to you since the location of the 
error is given as a line number in a procedure. 

• A description of the error. See Appendix B of this guide for a detailed explanation of the 
error messages. By modifying OPERRO.PAS, you can change the wording of Pascal run-time 
messages if you so desire. See the section on “Customizing Error Reporting” for details. 

• For I/O errors, the error code and the file name of the file causing the error. The error code 
is printed in both decimal and octal. On RT-11, all I/O error codes are errors detected by the 
support library and are described in Appendix B of this guide. The file name includes such 
information as the device name, file name and extension. 

• The location of the error in terms of line number and procedure name. The line number refers 
to lines in the overall source program, not statements in individual procedures. (For external 
procedures, the line number refers to lines in the external module.) A special case arises when 
a run-time error is detected in an external procedure compiled with nowalkback. In this case, 
the location of the error is given as an octal address. 

• The reverse sequence of active procedure calls back to the main program, if the error occurred 
at a level other than the main program. 

The walkback can be disabled at compile time; to do this, use the nowalkback compilation switch. 
When nowalkback is selected, the message header and the error message are printed but not the 
walkback. 


V 
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Examples 

Example 1. 

This example provides a look at a possible run-time error condition and the resulting error walkback. 
. RUN PACKER 

PASCAL—Fatal error at user PC= 2316B 
Array subscript out of bounds 

Error occurred at line 140 in procedure arrangetree 
Last called from line 326 in procedure svitchnodes 

Last called from line 402 in procedure getdep 

Last called from line 579 in program packer 

Example 2. 

A procedure called recursively may have many consecutive activations. In this case, the number of 
identical lines is indicated by the note (nn times) after the location description. Appearing below 
is the walkback of a program that looped recursively until the stack overflowed. 

. RUN EXTRA 

PASCAL—Fatal error at user PC= 5223B 
Stack overflor 

Error occurred at line 124 in procedure walk 

Last called from line 290 in procedure reanalysis (898 times) 

Last called from line 423 in procedure unloadbits 

Last called from line 440 in procedure matrixmask 

Last called from line 535 in procedure processleftop 

Last called from line 608 in program extra 

Example 3. 

This example illustrates the walkback produced as a result of an I/O error that is not trapped by 
the user. 

. RUN REFORM 

File to reformat: LSAT.TXT 

PASCAL—I/O error at user PC= 2166B 
Can't open file 

I/O error code= 11. (13B) in file: DK:LSAT.TXT 

Error occurred at line 44 in procedure openfile 
Last called from line 69 in program reformatter 
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Example 4. 

This example shows the walkback produced as a result of a run-time error in an external procedure 
compiled with nowalkback. Note that if the external procedure had been compiled with walkback 
(the default), the location of the error would be in source terms. 

. RUN DIFF8 

PASCAL—Fatal error at user PC= 1336B 
Division by zero 

Error occurred at location 1336 

Last called from line 32 in program dills 

I/O Error Trapping 

Pascal-2 permits you to write programs that trap and detect many kinds of I/O-related errors that 
normally would be fatal. Three predefined routines — procedure noioerror and functions ioerror 
and iostatus — facilitate this trapping of I/O errors. Using these routines, you have the ability 
to process I/O errors with your own code. You have two options: terminate the program at the 
occurrence of an I/O error (you can print your own diagnostics), or continue execution in spite of 
the error. The choice depends on the need. 

Since these three routines are predefined in the compiler, they do not need to be declared in your 
program. They accept a file variable as their only parameter. Details are supplied below. 

procedure noioerror: 

Specifies that the calling program will handle any I/O errors that result from read¬ 
ing or writing to the specified file. The file must be open before noioerror is called. 
This procedure performs the same function as the /go file control switch on reset 
and rewrite statements. 

function ioerror: 

Determines the status of the last I/O operation that the program performed on 
the specified file. This boolean function returns a true value if an I/O error has 
occurred, false if the operation was successful. 

function iostatus: 

Returns the integer error code that describes the last attempt to access a file. This 
function helps your program determine the cause of the error. Your program can 
either bypass the problem and continue processing, or terminate so you can cor¬ 
rect the problem. The I/O error is detected by the Pascal-2 support library. Pascal-2 
error codes, along with the text of the error message and a brief explanation of 
the cause, are listed in Appendix B of this guide. 

When you call these routines, you are responsible for checking the status of each I/O operation, to 
ensure that it was successful. If you fail to check the status and an error occurred, the results are 
unpredictable. 

The following program illustrates the use of these procedures. The program is designed to continue 
executing despite an I/O error. The call to noioerror indicates to the run-time system that errors 
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detected on the standard file input will be handled by the program, 
program Iotest; 


war 

I, Times: integer; 


begin 

No ioerror ( input); 
for Times := 1 to 4 do 
begin 

write ( 1 Type an integer: 1 ) ; 
read(I); 

if Ioerror(input) 

then writeIn('Error detected. Status^ 1 , 
else writelnCThe integer was: 1 , I: 1); 
readln; 
writeln; 
end; 

end. 


Iostatus(input)) 


If this program is compiled and run, the following results might be produced. The first entry results 
in a successful read of the integer I. The second and third entries result in a Pascal-2 run-time 
error. See Appendix B for a list of run-time error messages and associated numbers. The final entry 
is successfully read, and the program ends. (Under normal conditions, the first error would cause 
the program to abort.) 

. RUN IOTEST 

Type an integer: 1234 

The integer was: 1234 


Type an integer: 123456789 
Error detected. Status^ 23 

Type an integer: FFG 

Error detected. Status^ 23 


Type an integer: 
The integer was: 


77 

77 


The I/O error-trapping procedures can be used to determine the reason that a file could not be 
opened. To use this feature, specify the fourth parameter on calls to reset and rewrite. Specifying 
this fourth parameter keeps the reset or rewrite from trapping a normally fatal “open* error. 
This allows your program to recover and continue, or terminate under your control. 

The following program illustrates the use of ioerror and reset/rewrite. The program attempts 
to open a file called TEST.DAT on the device XXXX:, a fictitious device name. The error is detected 
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by Ioerror. 

program Opnerr; 


▼ar 

F: text; 

Status: integer; 
begin 

reset(F, •XXXX:', 'test.dat'. Status); 
if Ioerror(F) then 

writeln('I/O status*'. IostatusCF)); 

end. 

Wien this program is compiled and executed on RT-I1, it yields the following output. The value 11 
is the support library run-time error code for “can’t open file. 

RUN OPNERR 
I/O status* 11 


Customizing Error Reporting 

The flexibility of the Pascal-2 run-time organization allows you to not only handle I/O errors in your 
code but to customize the run-time error diagnostics to suit your needs. Included m the distribution 
kit are two Pascal source files, OPERRO.PAS and UERROR.PAS, which let you modify the way 
in which errors are reported. The object-file equivalents of these two procedures are m the Pascal 
support library. The changes you make can be used for a one-time debugging run, or they can 
permanently installed in the support library. 

OPERRO.PAS contains the entry point PSERROR, which the support library’s error-handling routine 
calls to print the message header and text of the run-time error message This source file is provided 
so you can change the wording of any error message simply by editing the source. 

UERROR.PAS contains the entry point PlUERROR, which is caUed following P$ERR0R to print addi¬ 
tional information about the error. This procedure contains two boolean constants set to false in 
the release version, each controlling (inhibiting) the printing of a septate set ofihagnostic^ 
with the booleans set to false nothing is printed. But by editing UERROR.PAS and settmgone 
more constants to true, you can receive a file dump of the offending file and/or a memory map of 
the program. The const fragment below shows the two constants. 


const 

Dump_Memory = false; { Print a memory map > 
DumplFile = false; { Print detailed file dump > 


By using UERROR.PAS, you can add your own code to UERROR.PAS for the printing of more 
specialized debugging information, and you can print out the values of critical vambles W n 
the program. To print variables you must include the program’s global variable declarations in 
UERROR.PAS. The ability to print critical variables is useful when you have a program wi many 
overlays or when the program is too large to run with the Debugger. 

When a run-time error is detected, several steps are taken: 


1. Control of the program transfers to the $ERR error-control module, in the Pascal support library. 
)ERR collects information about the error from the library data area. 

2. $ERR calls P$ERR0R (in OPERRO.PAS) to print the message header followed by the error 
message. 
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3. $ERR then calls P$UERR0R (in UERROR. PAS), which does nothing (by default) but can be 
modified to print a memory map of your program and/or dump the contents of the offending 
file. 

4. On return from P$UERR0R, the error-control routine $ERR transfers control to the Post-Mortem 
Analyzer (PMA), which prints the error walkback, and the program terminates. 

When you use a modified version of one or both of these procedures as externals, you need not declare 
them explicitly in the main program. After the altered version(s) of these procedures are compiled 
(with nomain), simply specify the module name(s) on the Linker command line after the program 
name. The Linker substitutes your version for the version in the support library. This sequence of 
commands should be used: 

. R PASCAL 
♦ PROG 
. R PASCAL 
♦ UERROR 
. R PASCAL 
♦ OPERRO 

. R LINK 

♦ PRQG=PRQG.UERROR.OPERRO.8Y:PASCAL 

Another way to override the version in the support library is to include the modified OPERRO.PAS 
and/or UERROR.PAS as part of the main program. The ^include directive does this easily. (See 
“Implementation Notes” in this guide for use of {{include.) 

For example: 

{{include 1 operro 1 ; 

{{include 1 uerror 1 ; 

When using the {{include directive, compile and link the main program as you normally would. 
The Linker resolves the references to P$ERRQR and P$UERR0R with the procedures included in the 
program. The program PROG, above, would be linked in this manner with these commands: 

. R PASCAL 
♦PROG 


. R LINK 

♦ PRQG=PRQG,SY:PASCAL 

The constant Dump.Memory, if set to true, causes the program to print a memory dump, or map, of 
the program showing the program’s use of memory. The map is printed by the external procedure 
memmap, a Pascal support library routine. Although memmap is declared in UERROR.PAS, you can 
use it with any Pascal program, independent of UERROR.PAS. Simply declare it in the program as 
an external with no parameters. The map helps you determine the way dynamic memory is being 
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allocated and perhaps the reason your program is running out of memory. 
. RUN DIAL 

PASCAL—Fatal error at user PC= 1276B 
Attempted reference through NIL pointer 


Memory Map: 

Pointer to top of stack - RESR6 : 140060B 

Pointer to global data - RESR5 : 13102B 

Standard Output :13076B 

Standard Input :13100B 

Saved Output** : 33256B 

Saved Input" :33316B 

Last file access : 

File 0 33256B TI : 

Active files : 

File 0 33316B TI : 

File 0 33256B TI : 

PMA active 
No free list 
No orphan list 
Last User PC 5116B 

Pointer to top of heap (P$KGRE) : 33556B 
Error occurred at line 29 in program dialphones 

The constant Dump ..File can be used to print a detailed dump of the Pascal and RT-11 file structures 
when an I/O error is detected. When Dump.File is set to true, the support library module fdump 
is called to dump information about the file. Programmers familiar with the structure of the file 
variable may find this information useful in diagnosing obscure file problems. 

The following listing is the file dump produced by fdump. Although you wouldn’t want the file dump 
printed at each occurrence of a run-time I/O error, in certain circumstances the file dump may help 
you diagnose more obscure errors. Lines such as “buffer size” display the information first in octal, 
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denoted by the B, then in decimal. 

. RUN COVER 

PASCAL—I/O error at user PC= 1072B 

File is not a random access file. Use /SEEK 

I/O error code= 27. (33B) in file: DK:LSAT.DAT 

File information for file variable at:34144B 
Contents of file Yariable: 

Ptr: 34204B Pointer to data in file buffer 
Stat:250B File status 

Records are Blocked 
Sequential File 
Read operations permitted 
Pending End of File 
Permanent File 

Non interactive device/.read 
Text file 

Current character not defined 

Name: DK :LSAT .DAT 
File Size in Blocks: IB 1. 

Channel : 15 
Current Block : OB 0. 

Buffer Address : 34204B 14468. 

Buffer Size : 1000B 512. 

Handler : RK: 

Device Info : 

Random Access Device 
Record Size in bytes : IB 1. 

Pointer to End of Valid Data : 34204B 14468. 
Records Per Block : 1000B 512. 

Terminal # : 0 
Last I/O Error : 27 

Error occurred at line 10 in program cover 
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Error Termination Status 

Both the Pascal-2 compiler and Pascal programs return a termination status when they exit. The 
Pascal-2 compiler terminates with a “severe error” status if it detects compilation errors. Upon 
detecting an error while running, such as “subscript out of bounds,” a Pascal program also will 
terminate with a “severe error” status. Otherwise, a “successful completion” status is returned. 

The termination status can be used by the command file processor and the batch processor to 
terminate a command stream that encounters an error. For instance, a command file that compiles 
and links a Pascal program can use the compiler termination status to detect any errors and skip 
the link step. 

The Exitst procedure is a support library routine that sets the termination status of an executing 
program when a “severe error” status is detected. The procedure’s integer argument determines the 
termination status for any program that calls it. When a “severe error” status of 4 is passed, the 
procedure also invokes the post-mortem analyzer to create a walkback of the program execution 
from the point of failure. Exitst takes its integer argument, as shown: 

procndurn Exitst(Status: integer); < procedure declaration > 

external; 

Call the procedure at a point in the program where you want to exit in case of a severe error, as 
shown: 

begin { program Severe > 

Exitst (4) ; —-terminate with severe status 

end. < program Severe > 

A status of 1 means normal termination; any other status means that an error terminated the 
program. 
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Multiple Source Files 

To combine multiple Pascal-2 files into a single compilation unit, you may use multiple input files on 
the compilation command line, the (include extended language feature within the program text, 
or both. 

The choice depends on the need. If, for instance, you are preparing programs for different machines, 
you can separate machine-dependent data from your individual programs and use the configuration 
data in a “header” file on the compilation command line. 

The (include directive allows the inclusion of separate text files within a program, thus simplifying 
the calling of external procedures. The directive is written as: 

(include ' fi/e-name-str/ng*; 

The contents of the file specified by fi/e-nam e-string are inserted at the point of the (include 
directive. The string must contain at least the name of the file; if no file extension is specified, .PAS 
is assumed. In addition to the file name and extension, fi/e-nam e-string can contain such information 
as the logical device name and disk volume number of the file. 

The single quotes enclosing fi/e-nam e-string are optional and provide portability to other 

implementations of Pascal-2. Despite their optional nature, we recommend that you use the single¬ 
quote delimiters on all (Include directives. 

Examples: 

(include 'hdr'; 

(include 'sy:string*; 

(include *dkO:libdef.pas'; 

Each included file may itself contain (include directives, to a maximum nesting of seven levels. 

The example below illustrates the use of both header files and the (include directive. 

Assume that the source file CONFIG consists of this: 

{ This file contains configuration data that is > 

{ subject to change froa installation to installation. > 

const 

MaxEntriee * 10; {entries allo«ed> 

Debug * false; {if true, sake debugging calls) 

Assume also that the source file COMDEF consists of this: 

{ This file contains the definitions of sows external ) 

{ procedures, together vith the type declarations seeded ) 

{ by the aaln prograa and the external routines. ) 

const 

laaeSlze * 24; {size of aaae field) 

type 

Dataltea = record {describes a custoaer) 

laas: packed array [1..laaeSize] of char; 

Age: 0. .aaxlat 
end; 


Updated January 1885 


2-44 









Implementation Notes 


procedure ReadDataCwar ThisItem: Dataltem; {result of read} 

Tar Done: boolean {No more items} ); 

external; 

procedure WriteData(ThisItem: Dataltem {item to write} ); 
external; 

And assume that the source file EXAMPL consists of this: 

^include 'comdef 1 ; 

Tar 

Base: array [1. .MaxEntries] of Dataltem; 

Bui: Dataltem; 

Counter: 0..MaxEntries; {count oi items in data base} 

1: 0.. MaxEntries; {induction Tar} 

Done: boolean; {set when no more items} 

begin 

Counter := 0; 
repeat 

ReadDataCBui, Done); 
if not Done then begin 
Counter := Counter + 1; 

Base[Counter] := Bui; 
end; 

until Done; 

{ Process data base } 

for I := 1 to Counter do 
WriteDataCBase[I]); 

end. 

These files are compiled with the command: 

. R PASCAL 
♦ CONFIG.EXAMPL 

The result is an object module, EXAMPL.OBJ, containing the output from the compilation of 
CONFIG, COMDEF, and EXAMPL, concatenated in that order. The object module can then be 
processed through the Linker to produce an executable image. 

Any compilation switches used will apply to all input files. 


Local Files Closed on Procedure Exit 

Consider a procedure (or function) that opens one or more files local to that procedure. Assume 
that the file variable for the file is defined local to that procedure. When the procedure exits and 
returns to the calling routine, all files defined local to that procedure are closed. This convention is 
necessary because upon procedure exit all local variables are deallocated. Once local variables are 
deallocated, they cannot be referenced again. Therefore, if a local file variable is deallocated, your 
program can no longer access that file, and no other program may access the file until your program 
terminates. 


2-45 











Pascal-2 V2.1/RT-11 Programmer’s Guide 


To prevent files opened in a procedure from being closed upon procedure exit, define the file variable 
as a global variable. Since the file variable is in the global data area, the file remains open and 
accessible until the file is explicitly closed or the program terminates. 

Specifying the Location of the Compiler’s Work Files 

The Pascal-2 compiler opens several temporary scratch files when it compiles a program. For large 
Pascal programs these files can become quite large (several hundred blocks) and they can be used 
quite heavily. The V2.1 compiler will attempt to open its scratch files on the logical device called 
IK: . If this logical device does not exist, the scratch files are opened on SY: , the system device. 

If you are running on a multi-disk system, and the disk you are using has very little free space, you 
can assign IK: to some other disk that has more room. Use the ASSIGN command to do this, as 
shown below: 

. ASSIGN DL1 IK 

This command associates the disk DL1: with the logical name IK:. The compiler then opens its 
scratch files on DL1:. 

If your system has different kinds of disks, you should assign IK: to the fastest disk on your system. 
This will reduce compilation time for large programs. You can experiment by using the times 
compilation switch to see if there is a significant change in compilation times with various disks on 
your system. 


Variable Initialization 

The Pascal standard states that variables must be initialized before they are used. Otherwise, their 
values are unpredictable. Pascal-2 catches most uninitialized variables but can’t possibly flag all of 
them. In short, variable initialization is the programmer’s responsibility. 

Obvious cases are easily detected, but more complex violations such as the initialization of I below 
are not caught by the compiler. 

var 

I, X: integer; 

begin 
read 00; 
if X <= 0 
then I := 0 — 

else I := I + 1; 
end. 

Reading Command Lines 

To prompt for and read the command line from an interactive program, simply write the prompt 
and read the command line, as shown in the following simple example: 

var 

CommandLine: packed array [1..80] of char; 
begin 

write O*') ; 
readln(CommandLine) ; 
write In (CommandLine); 
end. 


variable is initialized here 
-but not here 
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However, if you execute the above program as a batch job or an indirect command file, the RT-11 
batch processor still expects the command line to be entered from the terminal. This can defeat the 
whole purpose of running batch or indirect command files; you may want to be free to do other 
things while the batch job is executing. In this situation, the command line can just as easily be 
contained in the batch or command file. 

With the use of the support library procedure getlin, your program can read the command line from 
the batch processor as well as from the terminal. This flexibility allows you to write programs that 
can be executed in batch mode or interactively using the same method of obtaining the command 
line. 

The entry point getlin is defined in the support library in OPTRAP.MAC, a collection of run-time 
trap routines and entry points that must be in the root segment of any Pascal program that uses 
overlays. Getlin is declared as an external procedure. 

The call to getlin involves two entry points. The first entry point is getlin itself, which simply 
jumps to the second entry point, p$gtln. P$gtln, which is contained in the support library module 
OPGTLN.MAC, then writes the **' prompt and reads the command line. From p$gtln, control 
returns to the module that originally called getlin. 

The use of dual entry points to read a command line provides the ability to overlay the actual p$gtln 
code against the calling program without overlay conflicts. In this way you can process the command 
line in the first overlay segment, with the rest of the program overlaid in successive segments. 

NOTE 

Though p$gtln is a separate entry point callable from getlin, we recom¬ 
mend that you avoid calling p$gtln directly. The results can be unpredict¬ 
able. 

Getlin and its required parameters and data types must be declared in your program similar to the 
following: 

type 

Cmdlndex = 1 .. CmdLen ; 

CmdBuffer = packed array [Cmdlndex] of char; 
var 

Chuff: CmdBuffer; 

Cblen: Cmdlndex; 

procedure getlin (var Cbuff: CmdBuffer; { resulting line > 
var Cblen: Cmdlndex); { length of line > 

external; 

where 

CmdLen is the maximum length of the command line. The length of the command line should 
be at least 80 characters to allow for any command line up to that length. 

Cbuff is the packed array of characters into which the command line is read. Spaces may be 
used in the command line but are stripped off during the read. 

Cblen is the length of the command line in bytes. If Cblen is returned zero, a command line 
is not present. 

The support library passes the parameters to getlin through a temporary storage area, P$AREA. 
In this way both local and global variables can be passed to getlin without restriction. In addition 
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to protecting the command line from being trashed, P$AREA alleviates memory overwrite problems 
caused by the USR’s swapping in and out of memory to fulfill a request. 

The following sample program, FPRINT.PAS, shows a way to check for and read a file name specified 
in a command line. After it has read the file name, the program simply prints the contents of the 
file. 

program FilePrint; 
const 

CmdLen = 80; 
type 

Cmdlndex = 1..CmdLen; 

CmdBuffer = packed array [Cmdlndex] of char; 
var 

Chuff: CmdBuffer; 

Cblen: Cmdlndex; 

Filename: packed array [1..CmdLen] of char; 

Ch: char; 

I: integer; 

procedure getlin(var Chuff: CmdBuffer; { resulting line > 
var Cblen: Cmdlndex); { length of line > 

external; 
begin 

getlin(Chuff, Cblen); 
if Cblen <> 0 then begin 
for I := 1 to Cblen do 
FilenameCl] := Chuff[I]; 
reset(input,Filename); 
vhile not eof do begin 
vhile not eoln do begin 
read(Ch); write(Ch); 
end; 

readIn; writeIn; 
end; 
end 

else writelnCErr — No file 

end. 

Compile and link the above program with these steps: 

. R PASCAL 
♦ FPRINT 

. LINK FPRINT.SY:PASCAL 

The program then can be executed interactively or indirectly with the same results. Below, the 


{ make command line available > 
{ command line present > 

< open the input file > 

{ once per line > 

{ once per char > 


name given 1 ); 
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the contents of CODE.DAT is directed to the terminal. 

BfflLEEBUl - -interactive execution 

•CQPLJAI 

{ contents of CODE.DAT } 


For indirect execution, place the command and command line in a separate file with a .COM 
extension. FPRINT.COM could contain the following lines: 

ROI FPRIIT -the command 

CODE.DAT -the command line 

The at-sign indirect command symbol is used to execute the command file. 

• t FPRIIT 
.ROI FPRIIT 
'CODE.DAT 

{ contents of CODE.DAT } 


NOTE 

A possible drawback to the use of getlla is slower program execution, 
especially on floppy-disk systems that allow the USR to swap. 


Foreground Operation 

For foreground operation, allocate additional memory to ensure sufficient space for the stack, the 
heap, and file buffers. Each Pascal file requires about 300 words (more for large buffers), so allocate 
at least 600 words for the default input and output files. Use the /BUFFER: switch, as shown below. 
The period after 1024 signifies an octal value. 

.FRUI <fi/e-name>/RUFFER: 1024. 
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Lasy I/O 

For standard Pascal, an interactive inpat file, sack as terminal input, poses a problem. A program 
must always be able to determine the current status of an open file, i.e., it must be able to retrieve 
the current record from the buffer variable (F‘) and the current values of sola and eof. Since an 
interactive file is being created as it is being read, the program must periodically wait for you to 
enter a full line before it can determine the “end of line" (or the “end of file”) and keep the file 
well-defined. In this way the program is not synchronised with interactive input. 

Pascal-2 uses an input interface known as “lasy I/O" to handle input from text files. Since a file’s 
status needs to be defined only when the program actually refers to it, lasy I/O can safety delay 
any input operation until the program uses its results. When a Pascal program requests an input 
operation on a text file, the operation is recorded for later use. The delayed operation is triggered 
by any subsequent reference to the file’s buffer variable, the eof or the eoln value. The delay is 
invisible to the program but is visible to the user from the way the program is synchronised with 
interactive input. 

To use lasy I/O, you need to be aware of its effect on synchronisation of input and output operations. 
As an example, consider a simple program that reads its standard file inpnt, which is connected to 
a terminal. The program prompts for each line, and stops at the end of the file. The design of the 
program is dictated by two requirements: 

1. For the prompt to be effective, it must appear before the user is required to type the line. 

2. To detect the end of the file correctly, the program must check for it before reading each line. 

To meet both of these requirements, the program must print the prompt before an operation is 
performed that requires the next line of the file to be known: checking for “end of file” or reading 
the line. The following example shows this design. 

prograa Interactive(input, output); 
begin 

uriteCpronpt:'); 
while not eof do 
begin 
readln; 

uriteCpronpt:'); 
end 
end. 
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Incorporating Laejr I/O Into VM Programs 

Since lazy 1/0 changes the way Pascal-2 performs interactive I/O, programs compiled with Pascal-2 
Version 2.0 may have to be revised so they conform to the new scheme. For example, the 2.0 version 
of the above program might have been coded as follows: 

prograa Interactive(iapit, ontpnt); 
begin 

while not eof do 

begin 

vrlteCproapt:'); 
readIn: 
end 

end. 

If yon compile this program and execute it, the program appears to "hang.” In reality, the program 
is waiting for input; it is attempting to define the value of eof in the while statement, before it 
has the chance to write the prompt. Unfortunately, you will never see the prompt until you type 
in a line. This means that you will be prompted for the line you have just entered. In this case the 
program is “out of sync” with input from the terminal. 

Terminal I/O 

The FIT-11 terminal driver acts as an intermediary between a Pascal program and the video terminal 
from which it is running. The terminal driver, under operating system direction, collects characters 
one at a time and at end of line, sends a full line of text to the screen (for a write la) or to the 
executing program (for a readla). 

For example, when a read statement reads input from a terminal, the terminal driver reads each 
character and places it in an internal buffer until the terminal driver encounters an end of line (a 
carriage return, line feed, escape or Control-Z *Z). At this point, the terminal driver sends the entire 
line to the program and lets the program process the line one character at a time. 

The opposite is true for writ* statements, where no buffering is performed and each character is 
displayed on the terminal at the time the program writes it. 

As previously mentioned, the wrltoln statement directs the terminal driver to write the rest of the 
current line and prepare for the next line of output. The usual output sequence sent by the terminal 
driver is: data, carriage return, line feed. This sequence prints the data, returns the cursor to the 
first position of the newly printed line and moves the cursor to the beginning of the next line. 

The normal sequence of commands issued by the terminal driver may not particularly suit special 
I/O applications such as direct cursor addressing or special function key processing. To gain control 
of the terminal-I/O command sequence, use the /odt file control switch in conjunction with the 
/buffersixe:n switch on the reset statements. Used together, the /odt and /buffersize:l 
switches allow your program to read terminal input one character at a time without the need for a 
line terminator. To recognize special-function keys such as the PF1 (“gold”) key on VT100 keyboards, 
use the readsa procedure available in the Pascal support library. Both of these features are described 
in the following sections. 
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Single-Character or ‘ODT* Mod* 

On RT-11, single-character input between a video terminal and an executing Pascal program is 
accomplished with the use of the /odt and /baff#ralx*:l file control switches on the reset 
statement that opens TI : as the input file (treated as a test file). 

When the /odt file control switch is specified, each character read from the keyboard processed 
immediately without the program waiting for a carriage return or other action character. The 
/buffersize: 1 switch sets the terminal’s buffer size to 1 and places the device in single-character 
mode. 

Example: 

reset(input,•ti:/odt/bufferslxe:1•); 

A reset statement having these switches creates a new file control block and buffer and redirects 
all references to standard input to the terminal, known to the support library as TI:. Consequently, 
the library calls the system routine .TTTII rather than .BEAD to perform the terminal I/O. Beset 
overhead is minimal because no actual .LOOKUP is performed to open the file. 

In single-character or “odt” mode, a program reads input from the terminal one character at a time 
without waiting for a line terminator (i.e., the line-feed and escape characters). As a result, the 
programmer is responsible for echoing each character as it is read. 

NOTE 

Though not a line terminator per se, the BETUBI key terminates a line 
of input because it performs a carriage return then a line feed, which 
terminates the line. The null and carriage-return characters are ignored. 


When line-feed and escape characters are encountered, the eoin flag is set to true and input* 
points to a space. Likewise, detection of Control-Z (*Z) or the physical end of file sets oof to true 
and input* to a space. 
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progrin Slagle; 
nr 

Cl: char; 
begla { Slagle > 

resst(Input,'ti:/odt/bnfferslzs:1'); 
repeat { Forever — ead It with Coatrol-C > 
vriteCPrompt >'); 
while aot sola do begla 
read(Ch); 
write(Ch); 
ead; { while > 
readla; 
writela; 
aatll false; 
ead. < Slagle > 

Program Slagle prompts for input from the terminal. The characters you type appear to be echoed 
to the screen normally as they are typed. However, the program, and not the operating system, is 
doing the echoing (the write (Ch) statement). 

Function 'RsndSn* 

A second method for reading a single character from the terminal (a text file) entails the use of the 
Pascal support library function readsa. In addition to reading a single character at a time, readsa 
allows your program to recognize and correctly interpret the special function keys that are available 
on many terminals. 

Readsa has the same effect as “odt” mode with a one-byte buffer size and no character echo. Readsa 
does none of the normal text-file processing done by the support library, in which escape characters 
(<ESC>) are stripped from the file. Since readsa does not require a special buffer or file control 
variable, reads and readies from standard input still produce the expected results. You must, 
however, buffer the characters internally in your program if you wish to save the characters that are 
typed. 

Declare the function as an external, as shown: 
function ReadSa: char; external; 

The returned value of readsa is the current character read from the terminal. 

Special-function keys send a sequence of characters that is interpreted as one key. An example of 
special-function keys is the top row of keys on the VTlOO’s 10-key keypad marked PF1 to PF4. With 
the use of rsadsa, the sequence of characters making up special-function keys can be picked off one 
character at a time. For example, the PF1 key is made up of the three-character sequence ‘<ESOOP' 
(<ESC>, 0 and P). By reading the sequence one character at a time using rsadsa, a program caa 
determine that the PF1 key was pressed and not a carriage-return or line-feed key followed by ‘O’ 
then ‘P.’ 
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Random Aeeess to 'Text* Files 

The seek procedure cannot compote the location of a particular record (line) within a file of type 
text because the lines are of variable lengths. The Pascal support library supplies two external 
procedures, getpos and setpos, that simulate random access to text files. 

These two procedures are not predefined and must be declared in your program as external. Getpos 
determines the starting location of the next line of a file, and setpos sets the file pointer to the 
specified starting location of a line within the file. The beginning of each line of a text file is denoted 
by a block number and a byte offset into that block. Each block contains 512 bytes. The first line 
of a file starts with block 1, offset 0. If you try to access a nonexistent position or a position in the 
middle of a line, an I/O error will result. 

The block number and byte offset must be values returned by gatpos. You cannot compute the 
values yourself. When the file is being read, use gstpos to determine the starting position of the 
next line and save that block and offset combination for later use by setpos. 

Bear in mind that this is not “true” random access; yon cannot access individual characters, only 
individual lines of text. Use your Pascal program to access characters individually within each line. 

Procedure ‘GetPoe’ 

Procedure getpos determines the starting position of the next line to be read from or written to a 
text file. Getpos requires three parameters, passed by reference, as shown below: 

procedure GetPos(var F: text; var Block, Offset: integer); 
external; 

where 

F is the file variable of type text. 

Block is the returned disk block number of the next line in file F to be read or written. 

Offset is the returned byte offset into Block. Together, Block and Offset point to the next 
line to be processed. 

You should always call getpos to obtain the location in the file before you call setpos, so the block 
and offset values being passed to setpos are valid. 

The example in the next subsection shows the use of getpos. 
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Procedure ‘SetPoe* 

Procedure aetpos positions the file pointer to a specified block nnmber and byte offset into that 
block. Setpos accepts the same three parameters as fetpos, except Block and Offset are passed by 
value. The setpos declaration is as follows: 

procedare SetPos(rar F: text; Block, Ottaet : Integer); 
external; 


where 

F is the file variable of type text. 

Block is the block nnmber to which the file pointer is set. 

Offset is the byte offset into Block. Together, Block and Offset point to the new position. 

To stress an earlier point, the block number and byte offset must be values returned by gstpos. Do 
not attempt to compute the values yourself. Save the returned values for later use. 

If an error is detected while astpos tries to position the file, the end-of-flle flag sof is set to true. 
The losrror and lostatus support library functions may help you to determine the reason that the 
line could not be accessed. (For details on losrror and lostafcus, see “I/O Error Trapping” in this 
section.) If a file » positioned to a block and offset that does not correspond to the first character 
of a line, the results are unpredictable. 

The example below shows a way to use gstpos and setpos. Program Bsvsrss reads a text file and 
saves the position of each line in a linked list. It then prints the file in reverse line order so that the 
last line of the file is printed first and the first line is printed last. 
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prograa leverse; 
type 

Politer » *position; 
posltloa * 
record 

lest: politer; 

Block: liteger; 

Offset: liteger: 

ssd; 

var 

P: text; 

Fllesaas: picked irri j [1..60] of ckar; 

P, Z: politer; 

Doie: boo leu; 

procedire GetPos(fir F: text; fir Block, Offset: liteger); 
exteraal; 

procedire SetPos(var F: text; Block, Offset: liteger); 
exteraal; 

begla 

frite('File iaae? '); 
reidli (Flleuas); 
reset (F, Flleuas); 

P :» all; 

repeat 
■er(Z); 

with Z* do 6etPos(F, 

ZMext :« P; 

P :« Z; 

Doie :» eof(F); 

If lot Doie thei readli(F); 
util Doie; 

while P <> ill do < write the file ) 

with P* do begla 

SetPos(F, Block, Offset); -set pointer to start of next line 

If not eof(F) tkea begla 
while lot eola(F) do begin 
write(F*); 
get(F); 
eid; 

wrlteli; 

end; 

P :■ P*.Iext; 

end; 

end. 


{ read the file ) 

Block, Offset); -get start of next line 
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Unsigned Integer Conversion 

On the PDP-11, integer variables are stored in 16-bit words. These 16-bit words may be interpreted 
as signed or unsigned integers. A signed number, in two’s complement notation, represents numbers 
in the range —32767..32767. An “unsigned" (also called “extended-range") number by definition does 
not have a sign bit; rather, it uses all 16 bits to represent an integer in the range 0..65535. 

When their values are compared or used in mathematical expressions, unsigned integers differ greatly 
from signed integers. As an example, consider a word in which all 16 bits are set to one. This word 
has a value of -1 when interpreted as a signed integer, or a value of 65535 when interpreted as an 
unsigned integer. When this word is compared with some other value, the PDP-11 uses different 
combinations of instructions for signed and unsigned comparisons. If this number is multiplied by 
two, the result is a value of -2 for signed or 131070 for unsigned. The latter is an overflow condition 
because the result does not fit within 16 bits. 

The Pascal-2 compiler and support library also differ in their treatment of signed and unsigned 
integers. When you define a variable to be of type integer in your Pascal program, the compiler 
treats that value as a signed integer, unless you specify an unsigned integer using a subrange notation 
such as: 

type ' 

unsigned = 0..65535; 

var 

X: unsigned; 

According to your data declarations, the compiler will generate the correct code to compare, multiply, 
or divide unsigned numbers. The compiler can then deal with unsigned integers. 

However, if you attempt to write out the value of an unsigned integer, you will find that the number 
is always treated as a signed integer. This occurs because the Pascal support library uses a single 
routine to print integers. This routine interprets all integers as signed values. If you want to write 
out the value of an unsigned integer, use the following procedure in your program instead of the 
write statement. This procedure, Uwrite, takes an unsigned integer and a field width as arguments. 
The number is printed as a value in the range 0..65535, right justified in the specified field. 

procedure Uwrite(X: unsigned; 

Width: integer); 

{ This procedure writes an unsigned integer to output. } 
begin { Uwrite > 

if (X > 32767) and (Width >= 0) then 
begin 

if Width > 0 then 
Width := Width - 1; 
write(X div 10: Width); 

X := X mod 10; 

Width := 1; 
end; 

write(X: Width); 
end; < Uwrite } 

The PDP-11 floating-point hardware uses signed conversion when it converts an integer value to a 
real value. If you wish to convert an unsigned integer to real, use the following function. This 
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function, Ulloat, takes an unsigned integer as its argument and returns a real value in the range 
of 0.0 to 65535.0. 

function Ulloat(X: unsigned): real; 

{ This function converts an unsigned number to a real number. > 
var 

R: real; 

begin { Ufloat > 

R := X; 
if R < 0.0 

then R := R + 65536.0; 

Ufloat := R; 
end; { Ufloat > 

The trunc and round functions convert real numbers to integers. Since the floating-point hardware 
assumes a signed conversion, the following function should be used when an unsigned integer result 
is desired. The function Utrunc takes a real number in the range 0.0 to 65535.0 and converts it to 
an unsigned integer. 

function Utrunc(R: real): unsigned; 

{ This function converts a real number to an unsigned integer. > 

begin { Utrunc > 

if (R > 65535.0) or (R < 0.0) 
then writeIn('Unsigned number out of range 1 ); 
if R > 32767.0 

then R := R - 65536.0; 

Utrunc := trunc(R); 
end; { Utrunc > 

The unsigned round function is very similar to the above unsigned trunc function. 
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Compiler Optimizations 

The Pascal-2 compiler implements these optimizations: 

Variable Assignments to Registers 

The compiler permanently assigns up to three floating-point accumulators and two general registers 
to commonly used local variables in each block. The compiler assigns the registers to the variables 
that are the most often used. No register is assigned for variables passed to a procedure as a war 
parameter or referenced directly by a procedure local to the declaring procedure. In addition, this 
optimization is disabled for the main program if any external procedures are referenced, since the 
compiler cannot determine what variables may be used by such routines. 


Assignment of Constants and Addresses to Registers 

The compiler attempts to fill all registers with useful operands during compilation of a procedure, 
since operations on registers are faster and take less space than the corresponding operation per¬ 
formed in memory. Once a procedure is compiled, unused registers are filled with constant operands 
and addresses if such assignment saves space. This low-level optimization often results in a saving 

in execution time as well. 

. 


Constant Folding 

The compiler directly evaluates (folds) simple arithmetic involving constant operands of the types 
integer, char, real, and boolean. The generated code contains the result rather than the expres¬ 
sion. (The RT-11 SJ compiler does not fold real constants; the XM compiler does.) Set expressions 
and relational expressions are not folded. 

Dead Code Elimination 

If statements and case statements are optimized if the selection expression is constant. In this case 
only one path of execution is possible, and the compiler discards others. Knowledge of this optimiza¬ 
tion can lead to the writing of conditional code much like that available in some preprocessors. For 
example: 

if Debugging then write In(SomeUserValue); 

No code for this statement is generated if the identifier Debugging is defined as a constant with the 
value f alse. 

The debug compilation switch disables this optimization. 


Boolean Expression Optimization 

When appropriate, Pascal-2 uses the minimum number of operations necessary to compute the 
final value of operands in Boolean expressions, thereby reducing the cost of evaluating individual 
Boolean expressions. (This method is known as a “short-circuit" evaluation.) The programmer must 
be careful not to assume that all operands of Boolean operators are evaluated or that some may not 
be evaluated. (This optimization takes advantage of a provision in the Pascal standard that allows 
an implementation to evaluate only the necessary operands of a Boolean expression.) Also, the order 
in which the operands are evaluated is unpredictable. 
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Expression Targeting 

The compiler can determine from context where a particular expression result should be computed. 
For instance, procedure parameters can often be computed directly on the run-time stack, and at 
times, expressions on the right side of the assignment operator can be computed directly into the 
variable on the left side. 


Common Subexpression Elimination 

Multiple occurrences of the same expression are detected and simplified. Such optimization of 
redundant expressions is needed even though a programmer can often avoid writing such code by 
introducing auxiliary variables. For instance, this example: 

writeln(I + 1, I + 1); 

may be simplified to: 

J := I + 1; writelnCJ, J); 

The simplification avoids the redundant computation. However, redundancy of the sort shown in the 
first example often leads to a more readable program. Also, certain classes of redundant expressions 
cannot be eliminated in the source program. For instance, array index calculations involve several 
underlying operations that are not reflected in the source code and therefore cannot be simplified 
by the programmer. Pascal-2 eliminates a wide class of common subexpressions, across statement 
boundaries as well as within simple expressions. 

The debug compilation switch disables this optimization. 

Common Branch Tail Elimination 

In some cases the compiler generates several branches to the same location in the object program. At 
times the compiler can replace redundant instructions preceding one such branch instruction with 
a branch to a point in the generated code that executes the same instruction stream. This low-level 
optimization executes an extra branch instruction in order to save some space. 

The debug compilation switch disables this optimization. 


Array Index Simplification 

Index expressions of the form [variable 4- constant] and [variable — constsmt] are partially computed. 
The addition or subtraction of the constant operand is folded into the value computed for the base 
of the array. This optimization is enabled only if array bounds checking is disabled and the array 
is unpacked. 
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Appendix A: Compilation Error Messages 

’(’ expected 

Check parameter list syntax. 

expected 

Check parameter list syntax. 

’,' expected 

Check parameter list syntax. 

. 9 ..• expected 

Check array specification. 

’:’ expected 

Check type or var specification. 

' : = ' expected 

Check for undefined procedure or missing colon. 

•;* expected after procedure body 

Use semicolons to separate procedure declarations. 

' = ’ expected 

Check constant or type syntax. 

*[’ expected 

Check array index specification. 

’]’ expected 

Check array index or set specification. 

']' or 'must follow index expression 

Check array index specification. 

A TYPE identifier is not allowed here 

The compiler encountered a bad structured constant or misplaced identifier. 

Actual parameter cannot be used with this conformant array parameter 

When conformant array parameters are used, the actual parameter must be an array 
and its type must be compatible with the formal parameter type. 

Actual parameter type doesn't match formal parameter type 

Parameters being passed to procedures must have the same type names as the declared 
(formal) parameters. 

All parameters in a single parameter section must have the same type 

Parameters grouped under one conformant array schema must be of the same type. 

Ambiguous switch 

The specified command-line switch name does not contain enough characters to distin¬ 
guish it from switches with similar names. 
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Array exceeds addressable memory 

Array subscript out of range 

Assignment of file variables not allowed 

An attempt has been made to assign an expression to a file variable or one file vari¬ 
able to another. 

Assignment operands are of differing or incompatible types 

Type mismatch — compare left and right sides of assignment statement for compatibility. 
Note that pointer types must point to identical data structures. 

Assignment to constants not allowed 

Assignment value out of range 

Bad adjust offset value in procedure <name>/main program 

A compiler consistency-check error; please file a Trouble Report immediately. See Appendix 
C of this guide for more information. 

Bad CASE label 

Case labels and case selectors must be of the same type. A colon, erroneously placed 
after the keyword otherwise, can also cause this error. 

Bad IN operands 

The left operand must be of a scalar type; the right operand must be of a compatible 
set type. 

Bad ORIGIN value 

Origin values are restricted to the I/O page (locations 0 to 1000 octal) or the system 
area (28K to 32K). 

Bad constant 

Bad file name syntax 

Check command-line syntax. 

Bad parameter element 

The indicated parameter element was not followed by a V or a *)\ 

Bad type syntax 

Badly formed expression 

Check parentheses and operator placement. 

BEGIN expected 

The statement part of a block must start with begin. Modules with no main program 
require the nomain compilation switch. 

Binary operator expected 

Two operands must be separated by an operator. Also check for mismatched quotesor 
an illegal digit in the cross-hatch *#’ integer form. 
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Block declarations axe incorrectly ordered 

The relaxed ordering of declarations is an extension to 
only for global declarations. 


standard Pascal and may be used 


Block ended incorrectly 


Block must begin Tith LABEL, CONST, TTPE, 


VAB. PROCEDURE, FUNCTION, or BEGIN 


Boolean value expected 

Can't assign a real value to an integer variable (use TBUNC or ROUND) 
Can't pack unstructured or named type 
CASE label defined twice 

CASE label does not match selection expression type 
CASE label must be non-real scalar type 


CASE label type does not match tag field type 

CASE selection expression must be a non-real scalar type 


Code too complex in procedure <name>/main program , _ . 

The named body of code is too complex to be compiled. Restructure the progr 
reduce its complexity. See Appendix C of this guide for more information. 

i nr writer error — please contact Oregon Software at (503) 226-7760 
^ This indicates an internal compiler error - please save all listings and terminal output. 

COn *Certain s^itch^comMnations cannot be specified together on the compiler commandline. 
The debug switch conflicts with both the profile and errors switches; the profile switch 
conflicts with the errors switch; and the object switch conflicts with the macro switch. 


Declaration terminated incorrectly 

Declared labels must be defined in procedure body 


DO expected 

Check for, while or with statement syntax. 

END expected 

Exponent must lie in range -38..38 

Expression type is incompatible with FOB index type 
For statement index types must, be non-real scalars. 

External procedures/functions must be defined at outermost level 
External procedures may not be defined within other procedures. 


2-63 





Pascal-2 V2.1/RT-11 Programmer’s Guide 


Extra END following block — Check BEGIN ... END pairing 

Extra procedures found after main program body 

This error occurs when more than one main program body (starting with a program 
statement) appears in the source file. 

Extra statements found after end of program 

This error occurs when more than one main program body appears in the source file, 
or when the nomain compilation switch is used with a source file that contains a main 
program body. 


Field variable expected for NEV 

Additional parameters to new must be tag-field constant values that identify the par¬ 
ticular variant record being allocated. 


File 


cannot contain a file component 
An element of a file cannot itself contain a file. 


File names in RESET/REWRITE are non-standard 

This error is generated only when the standard compilation switch is enabled. 


File variable expected 

The first parameter to reset, rewrite, get, put, and seek must be a file variable. 


File variable or pointer variable expected 

The indicated caret (*) has been incorrectly placed after a variable that was neither 
a pointer nor a file. 


Files must be passed as VAR parameters 


FOR-loop control variable can only be a simple nan-real scalar variable 


FOR-loop control variable must be declared at this level 

A for statement control variable must be declared local to the block containing the 
for statement. 


Format expression must be of type INTEGER 

Field-width specifications in write or writeln statements must be integers. 


Forward procedure/function body is never defined 

Forward type reference is never resolved 

The type referenced in a pointer type declaration is not defined by later declarations. 


Function cannot be applied to an operand of this type 

A standard function has been passed a parameter of the wrong type (for example, trunc/round 
can only be applied to real types). 

Function identifier is never assigned a value 


Function name expected 
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Function result oust be of scalar or pointer type 

Functions may not return structured types such as records and arrays. Use var parameters 
to do this. 

Function result type cannot be duplicated in forward-declared function body 

The parameter list and result type are already specified by the forward declaration and 
may not be repeated. Instead, simply give the function name. 

Identifier cannot be redefined or defined after use at this level 

The specified identifier is already defined in the current block and cannot be assigned 
a new meaning in the indicated block. 

Identifier expected 

The indicated argument should be a variable, not a constant or expression. 


Illegal character 

Illegal comparison of record, array, file, or pointer values 

Pointer types may be compared only for equality; record, array, and file types may not 
be compared in any case except strings. 

Illegal function assignment 


Illegal subrange 

The lower bound of a subrange is required to be less than or equal to the upper bound. 


Index expression type does not match array declaration 
Index must be non-real scalar type 


Index variable missing in this FOR statement 
Integer label expected 
Integer overflow or division by zero 
Integers must lie in range -32767..32767 


Internal temp error in procedure <name>/main program 

A compiler consistency-check error; please file a Trouble Report immediately. See Appendix 
C of this guide for more information. 


Label cannot be redefined at this level 

Labels may be redefined within nested procedures, but not at the same level. 

Label defined twice 

Label is target of illegal GOTO 

Branching into if-then-else or 9 ase statements is illegal. 

Label must be declared in LABEL declaration 


2-65 





Pascal-2 V2.1/RT-11 Programmer’s Guide 


Label must be unsigned integer constant 
Line too long 

The maximum input line length is 100 characters. 

Listing requested but no file provided 

Check command-line syntax. 

More than two output file specifications 
Check command-line syntax. 

Must assign value before using variable 

The standard states that variables must be initialized before they are used. 

Must use VAR parameters with NONPASCAL directive 

The calling sequence for nonpascal procedures and functions accepts only call-by-reference 
parameters. 

Need at least 1 digit after or 'E' 

Check for proper real numeric format. 

Need at least one value to TRITE 

Need at least one variable to READ 

No file in field 

Check command-line syntax. 

No input file provided 

Check command-line syntax. 

"NO” not allowed on this switch 


No strict inclusion of sets allowed 

The operators *<’ and *>* may not be applied to set operands. Instead, use *<=’ or < >=\ 

Non-decimal integers are not standard Pascal 

This message is issued only when the standard compilation switch is specified and the 
cross-hatch integer form is used. 

Non-standard comment form, please use or "(*■ 

The comment form ‘/* 9 , **/ 9is not accepted by Pascal-2. The PASMAT utility automati¬ 
cally converts non-standard comments to the standard form. 

Nonsense discovered after program end 

Extraneous characters are present in the input file after the proper end of the program. 

Octal constant contains an illegal digit 
Octal constants cannot contain an 8 or a 9. 
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Octal constants are not standard Pascal. 

This message is issued only when the standard compilation switch is specified and the 
conventional octal form containing ‘B’ is used. 

OF eipected 

Check file or set declaration syntax, or case statement syntax. 

Only 15 levels of nesting alloved 

The compiler’s limit for procedure and function nesting has been exceeded. 

Only functions can be called from expressions 

Procedures do not return a value and may not be called from within expressions. 

Operand expected 

Operands are of differing or incompatible type 

Operator cannot be applied to these operand types 

Check the indicated expression for proper form and operand type compatibility. For ex¬ 
ample, characters may not be multiplied together. 

OTHERWISE/ELSE clause in CASE not allowed 

Otherwise is an extension to standard Pascal. This message is issued when the stan- 
dard compilation switch is specified. 

Out of memory in procedure <name>/main program 

The named body of code is too large or too complex to be compiled. Restructure the 
program to reduce its complexity. See Appendix C of this guide for more information. 

Output requested but no file provided 
Check command-line syntax. 

Packed array [1..n] of characters expected 

The file name arguments in reset and rewrite must be strings. 

Packed conformant array parameters cannot be nested 

Only one index type specification is allowed for packed conformant array parameters. 

Parameter list cannot be duplicated in forward-declared procedure/function body 
The indicated statement should simply give the procedure name and no parameters. 

Pointer variable expected 

Procedure name expected 

Procedures cannot be followed by type definition 

The relaxation of declaration ordering applies only to global declarations, and to declara¬ 
tions in inner blocks which precede procedure and function definitions. The indicated 
declaration section is improperly placed. 

PROGRAM heading expected 

This error occurs only if the standard compilation switch is set. 

Radix of non-decimal constant must lie in range 2.. 16 
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READLN and YRITELN must be applied to text file 

Reassignment of FOR-loop control variable not alloved 

The control variable of a for statement may not be modified inside the body of the 
for statement. 

Record identifier expected 

A with statement must specify a record variable. 

Required parameter missing 

The indicated command-line switch requires a parameter as part of the switch. Consult 
the section in this manual on compilation switches for the required parameter. 

Same switch used twice 

Check command line for duplicate switches. 

Set is constructed of incompatible types 

Set types must have a base in the range 0. .255 

Sets must be non-real scalar type 

The indicated set definition contains an illegal component type. 

Statement ended incorrectly 

String constants may not include line separator 

A closing single quote (’) is missing. 

String of length zero 

Strings must contain at least one character. 

Tag does not appear in variant record label list 

The tag field referred to does not exist. 

Tag identifier already used in this record 

Field identifiers within a record are required to be unique and may not be redefined 
within that record. 

The divisor of a MOD must be greater than zero 

THEN expected 

Check if statement form. 

This function was declared as a forward procedure 

Conflict between declaration and use of function identifier. Check previous declaration. 

This parameter cannot be followed by a format expression 

A format expression may appear only in calls to write and writeln. 

This procedure was declared as a forward function 

Conflict between declaration and use of procedure identifier. Check previous declaration. 

This procedure/function name has been previously declared forward 

A procedure cannot be both forward and external, or both forward and nonpascal. 
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TO or DOINTO expected 

Check lor statement syntax. 

Too lex actual parameters 

The indicated parameter list does not agree with the procedure or function parameter 
definition. 

Too many actual parameters 

The indicated parameter list does not agree with the procedure or function parameter 
definition. 

Too many errors! 

The compiler error table holds 50 error messages. Error processing is terminated. Correct 
earlier errors and recompile for further checking. 

Too many external references in procedure <name>/main program 

Programs are limited to 256 external procedure references. See Appendix C of this guide 
for more information. 

Too many forward references (only BO allowed) 

Too many identifiers (only 1697 allowed) 

Too many keys in procedure <name>/main program 

The named body of code is too complex to be compiled. Restructure the program to 
reduce its complexity. See Appendix C of this guide for more information. 

Too many labels in procedure <name>/main program 

The limit of 280 case labels has been exceeded in named body of code. Restructure 
the program to reduce its complexity. See Appendix C of this guide for more information. 

Too many nested INCLUDE directives (only 8 allowed) 

Too many nodes in procedure <name>/main program 

The named body of code is too large to be compiled. Restructure the program to reduce 
its complexity. See Appendix C of this guide for more information. 

Too many Pascal labels in procedure <name>/main program 

More than 32 statement labels have been declared in named body of code. Restructure 
the program to reduce its complexity. See Appendix C of this guide for more information. 

Too many procedures (only 300 allowed) 

Too many strings or identifiers 

Restructure the program to reduce its complexity. 

Too much object code in procedure <name>/main program 

The named body of code is too large or too complex to be compiled. Restructure the 
program to reduce its complexity. See Appendix C of this guide for more information. 

Two file names in one field 

Check the command line for missing *=’ or V* 
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Travrs build error in main program 

A compiler consistency-check error; please file a Trouble Report immediately. See Appendix 
C of this guide for more information. 

Travrs walk error in main program 

A compiler consistency-check error; please file a Trouble Report immediately. See Appendix 
C of this guide for more information. 

Type name expected 

The first parameter passed to the loophole function must be a type name. 

Unable to open compiler scratch files 

The disk in use does not have enough free space to store the compiler’s scratch files. 
Try assigning IK: to a different disk. 

Unary or cannot be applied to set operands 

Undefined identifier 

Undeleted temps in procedure <name>/main program 

A compiler consistency-check error; please file a Trouble Report immediately. See Appendix 
C of this guide for more information. 

Unexpected ’)’ — Check for matching parenthesis 

Unexpected ELSE clause — Check preceding IF for extra *; * 

Unknown directive 

The legal directives are ^include and Xpage. 

Unknown switch 

Check command line for error. 

UNTIL expected 

Check repeat statement for proper form. 

Use *. 1 after main program body 

The indicated terminator is missing from end statement. 

Use ’;’ to separate declarations 

In addition to flagging the usual missing-semicolon errors, this message is issued when 
an illegal digit for the specified radix is found in the cross-hatch format for constants. 

Use ';' to separate statements 

Value for qualifier out of range 

A value supplied with the indicated command-line switch is not within the allowable 
range for that switch. 
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VAR parameters cannot be passed an expression or packed field 

A var parameter must be the name of a variable or a component of a data structure. 
If the parameter is a component of a data structure (record or array), the structure 
may not be packed. 

Variable name expected 

Variable of type ARRAY expected 

Variable of type RECORD expected 

Variables of this type are not alloved in READ 

Scalar variables may not be used in either read or write to a text file. Only predefined 
types (except boolean) and strings may be read from a text file. 

Variables of this type are not allowed in VRITE 

Scalar variables may not be used in either read or write to a text file. Only predefined 
types (except boolean) and strings may be read from a text file. 

Variant label is undefined 
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2 Array subscript out of bounds 

An array index is outside of the limits established for the array in the type declara¬ 
tion that defines the array. 

44 Attempt to access block > 65635 

RT-11 files cannot contain more than 65535 blocks. 

17 Attempt to read past end of file 

An input operation was attempted on a file when eof is true. This is usually due to 
a logic error in the program and can often be solved installing checks for eof. This 
error can be trapped with the noioerror procedure. 

15 Attempt to write past end of file 

Files cannot be dynamically expanded. To increase the number of blocks allocated to the file, 
specify a larger value for the fourth parameter on the rewrite statement that opens the file. 

33 Attempted reference through NIL pointer 

A pointer variable was improperly used while its value was undefined or nil. This er¬ 
ror could be the result of a pointer being disposed of before it is used, or of a value 
never being assigned to it. This could also occur if the pointer was created with loophole 
or ref. The $nopointercheck switch suppresses this error message. 

41 Can’t delete file 

The specified file cannot be deleted. This error can be trapped with the noioerror procedure. 
11 Can’t open file 

The file could not be opened for the reason identifed by the I/O error code. For input 
files, this error usually occurs if the file does not exist. You can trap this error by specifying 
and checking the fourth parameter on the reset or rewrite statement used to open the file. 

42 Can’t rename file 

The file could not be renamed for the reason given by the I/O error code. This er¬ 
ror can be trapped with the noioerror procedure. 

37 CASE selector matches no label 

A case selector expression has no matching case label. The otherwise clause can be 
used to detect this error. The $norangecheck switch disables the detection of this error. 

30 Compiler/library mismatch 

The compiler version used to compile the main program does not match the support 
library used when the program was linked. This error could occur if a new version of 
Pascal-2 is installed on your system, and you attempt to link a program with a module 
compiled with an older version of the compiler. The solution here is to recompile all 
of your modules. This error could also happen if the compiler or library were updated 
independently. You might have to rebuild the compiler for your system. 

35 DISPOSE0 of a NIL pointer 

The pointer value does not point into the heap memory pool. This error could occur 
if the pointer is not initialized (via new) or if the pointer was created with loophole or ref. 
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5 Division by zero 

Division by zero is not defined. 

22 Double deallocation of dynamic memory 

The pointer variable points to an area of memory already available for reuse. Possibly 
the pointer was not initialized, or it was created with loophole or ref. Also, the heap 
may have been corrupted. This can happen if you make assignments using uninitial¬ 
ized pointers or if an external procedure is called and the number of parameters passed 
to the procedure differs from the procedure definition. 

18 Error reading file 

An I/O error was detected while your program was reading an input file. The I/O er¬ 
ror code describes the exact cause of the error. This error is most often reported dur¬ 
ing a read or a get operation. This error can be trapped with the noioerror procedure. 

19 Error writing file 

An I/O error was detected while your program was writing an output file. The I/O 
error code describes the exact cause of the error. This error is most often reported dur¬ 
ing a write or put operation. This error can be trapped with the noioerror procedure. 

8 EXPO overflow 

The parameter passed to the exp routine would cause an overflow condition during the 
calculation of the exp. The maximum value permitted is approximately 88. 

- - Fatal initialization error 

This error indicates that the Pascal support library could not properly initialize the program 
for the reason given. This error usually occurs when the program is too large. 

27 File is not a random access file. Use /SEEK 

This error is caused by an attempt to use the seek procedure on a file that was not 
opened with the /seek I/O control switch. The /seek switch must be used with the 
reset or rewrite statement that opened the file. This error can also occur if you at¬ 
tempt to open a sequential device such as a terminal or printer using /seek. 

38 File is not an input file 

An input operation was attempted on a file that has not been prepared for reading by reset. 
Be sure to use the /seek I/O control switch when you are opening random access files. 

39 File is not an output file 

An output operation was attempted on a file that has not been prepared for writing 
by rewrite. 

14 File name syntax error 

The file name is not a valid file specification. Check the file specification for invalid 
characters or other garbage in the file name. You can trap this error by specifying the 
fourth parameter on the reset or rewrite statement used to open the file. 

29 File not open 

All files other than input and output must be opened with reset or rewrite before 
they can be accessed. 
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6 Floating point format error 

The program attempted to read a real number from a text file, where the data in 
the file is not a valid real number. This error can be trapped with the noioerror procedure. 

3 Floating point overflow 

The result of a floating-point operation is too large to represent as a real number. The 
magnitude of the largest real number is approximately 1.7 E + 38. 

25 Floating point support error 

This error results from a floating-point error condition other than real overflow, integer 
overflow or division by zero. 

32 I/Q transfer error 

A hard error (i.e., device not ready, timing error, hardware read or write error) has 
occurred on the channel doing the transfer. Consult the RT-11 Software Support Manual 
for further assistance. 

23 Illegal value for integer 

The program attempted to read an integer value that lies outside the range —327A7..32767. 
This error can be trapped with the noioerror procedure. 

9 LOGO of zero or a negative number 

Logarithms are only defined for positive values. 

- - Multiple errors detected. Program aborted. 

This error occurs when an error is detected while another error is being processed. Rather 
than printing a possibly infinite list of errors, the support library prints this special er¬ 
ror message and terminates the program. This error can be caused when the support 
library code has been accidentally overwritten. 

21 NEWQ of zero length 

This error usually indicates 1 an internal error in the Pascal support library. It could also 
be caused by an incorrect call to the p$inew function. 

1 Not enough memory. 

The new procedure was unable to allocate the requested block of memory. Dispose of 
noncritical memory or decrease the number of open files. 

43 Odd address or nonexistent memory trap 

An invalid memory location has been referenced. This error is the same as the PDP- 
11 “trap to 4” error. 

40 RENAME/DELETE of non-disk file 

The use of rename and delete is restricted to random-access devices only. Here the 
program attempted to perform a illegal (and meaningless) rename or delete operation 
on a non-disk device such as a line printer. 

28 Reserved instruction execution 

Several problems could cause this error. Check for the improper use of overlays or a 
mismatch between external procedure definitions and references. If this error happens 
on a statement involving real numbers, you may have configured your Pascal-2 system 
incorrectly. 
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26 SEEECQ out of range 

The program attempted to “seek” a nonexistent record. Record numbers begin with 1 
and end with the last record of the file. Attempts to access record numbers less than 
1 or greater than the last record (past the end of file) will cause this error. 

24 Set element out of range 

The program attempted to reference an element of a set that is outside the range of 
values permitted in the set. The valid range, is 0..255. 


7 SQRTO of a negative number 

The square root of a negative number is undefined. 


37 Stack overtlov 

This error could be caused by an overly large program, excessive use of dynamic memory, 
or deeply nested recursion. If appropriate, try overlaying the program, or close unused 
files and dispose of unused memory. 



Too many files open 

No more channels are available to the program. Sixteen channels are normally avail¬ 
able (0 through 15) unless the program is overlaid, in which case the operating sys¬ 
tem uses channel 15 for overlays. Close any unused files. 


20 TRUNC/ROUND overflow 

The result of a trunc or round operation is too large to be represented. Only real num¬ 
bers in the range -32767.0 to 32768.0 may be converted to integers with the trunc 
or round functions. 

- - Unknown Pascal run-time error #ntzjzi 

This message indicates that the detected error has no corresponding error message text. 
This indicates an internal error in the support library. Contact Oregon Software or file 
a Trouble Report. 



10 


Unrecognized file switch 

An I/O control switch specified on a reset or rewrite statement is unknown to the 
file system. Check the spelling of your file switches. You can trap this error by specify¬ 
ing the fourth parameter on the reset or rewrite statement that opened the file. 


34 Variable subrange exceeded 

The program attempted to assign a value to a variable that is outside the bounds of 
the subrange type. This error is often caused by uninitialised variables or the improper 
use of subrange definitions. The $norangecheck switch disables the detection of this error. 
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Appendix C: Compiler Errors 


Overflow Errors 

Very complex or very large programs may exceed the capacity of the Pascal-2 compiler. Overflow 
of this sort is reported directly to the terminal rather than to the listing or error file. The compiler 
reports the type of overflow along with the name of the procedure causing the problem. Overflow 
errors may also occur in the main program. The following list of error messages assumes that a 
procedure named MuchTooComplicated has caused an overflow: 

Too many keys in procedure MuchTooComplicated 

Out of memory in procedure MuchTooComplicated 

Too many labels in procedure MuchTooComplicated 

Too many nodes in procedure MuchTooComplicated 

Code too complex in procedure MuchTooComplicated 

Too much object code in procedure MuchTooComplicated 

Too many Pascal labels in procedure MuchTooComplicated 

Too many external references in procedure MuchTooComplicated 

An overflow condition in the main program will be reported as: 

Too many keys in main program 

If compilation of a program causes one of the above error conditions, simplify the offending procedure 
or main program section. Two suggested ways to do this are to split the routine into several sub- 
procedures and/or reduce the number of type definitions. 

Consistency Checks 

In addition to the above error messages, consistency checks within the compiler can (in theory) 
trigger one of these errors: 

Undeleted temps in main program 
Internal temp error in *»«••** prog r am 
Travrs build error in main program 
Travrs walk error in main program 
Bad adjust offset value in ma.-in prog r am 
nnn consistency checks detected 

You should seldom, if ever, see consistency-check errors; they are documented here for the sake 
of completeness. If you do see such an error, please send us a Trouble Report immediately. Along 
with the Trouble Report, send us the smallest possible source program that reproduces the error. 
Programs longer than one page should be sent on floppy disk or magnetic tape. (You also may call 
Oregon Software at 503-226-7760, but we will undoubtedly need to have the problem in writing.) 






Appendix D: Default File Extensions 


Appendix D: Default File Extensions 

The default file extensions listed here apply to files generated by and/or referenced by Pascal-2 and 
its utilities. The first column lists the type of data contained in the file. The second column lists the 
extension. 


File 


Extension 


Document 

.DOC 

Executable 

.SAV 

Listing 

.LST 

MACRO-11 Source Code 

.MAC 

Object 

.OBJ 

PROCREF Output 

.PRF 

Profiler Output 

.PRO 

PROSE Input 

.PRS 

Source 

.PAS 

Symbol Map 

.SMP 

Symbol Table 

.SYM 

Temporary 

.TMP 

XREF Output 

.CRF 


2-77 








Pascal-2 V2.1/RT-11 Programmer’s Guide 


Appendix E: Entry Points in the Pascal Support Library 

Entry 

Point Description 

P$0 Read character from standard file input 

P$1 Double-precision division simulation 

P$2 Read character from file 

P$3 Double-precision multiplication simulation 

P$4 Read integer from standard file input 

P$5 Double-precision subtraction simulation 

P$6 Read integer from text file 

P$7 Double-precision real addition simulation 

P$8 Read real number from standard file input 

P$9 Read double-precision real from standard file input 

P$10 Read real number from text file 

P$ll Read double-precision real from text file 

P$12 Read string from standard file input 

P$13 Permanently undefined (unlucky) 

P$14 Read string from text file 

P$15 Reserved 

P$16 Readln on standard file input 

P$17 Reserved 

P$18 Readln from text file 

P$19 Reserved 

P$20 Write character to standard file output 

P$21 Reserved 

P$22 Write character to text file 

P$23 Reserved 

P$24 Write integer to standard file output 

P$25 Reserved 

P$26 Write integer to text file 

P$27 Reserved 

P$28 Write real number to standard file output 

P$29 Write double-precision real to standard file output 

P$30 Write real number to text file 

P$31 Write double-precision real to text file 

P$32 Write string to standard file output 

P$33 Initialize standard files input and output 

P$34 Write string to text file 

P$35 Set user-handling of I/O errors for file (noioerror) 

P$36 Vriteln to standard file output 

P$37 Status check of last file operation (ioerror) 

P$38 Vriteln to text file 

P$39 I/O error code of last file operation (iostatus) 

P$40 Reserved 

P$41 “Stack overflow” error message 

P$42 Reserved 

P$43 “Subscript out of bounds” error message 

P$44 Reserved 
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Entry 

Point Description 

P$45 “Variable subrange exceeded” error message 

P$46 Reserved 

P$47 “Reference through a nil pointer* error message 

P$48 Reserved 

P$49 “Case selector* error message 

p$50 Reserved 

P$51 “Division by zero* error message 

P$52 Reserved 

P$53 Delate file 

P$54 Reserved 

P$55 Rename file 

P$56 Reserved 

P$57 Close files in specified range 

P$58 Reserved 

P$69 Initialize Pascal 

p$60 Put next record 

P$61 Get next record 

P$62 Break file 

P$63 Program termination 

p$64 Rewrite file 

p$65 Seek record in file 

P$66 Reset file 

P$67 Debugger initialization 

p$68 Close file 

p$69 Debugger procedure entry 

p$70 New memory allocation 

p$71 Debugger procedure exit 

P$72 Dispose memory deallocation 

P$73 Debugger non-local goto 

p$74 Reserved 

p$75 Save registers 

p$76 Reserved 

p$77 Restore registers 

P$78 Signed integer multiply 

p$79 Reserved 

P$80 Signed integer divide 

p$81 Pack 

p$82 Signed integer mod 

p$83 Unpack 

P$84 Floating compare simulation 

P$85 Double-precision floating compare simulation 

p$86 Trunc of real number 

P$87 Trunc of double-precision real 

P$88 Float conversion to real 

P$89 Float conversion to double-precision real 

P$90 Sqrt of real number 

P$91 Sqrt of double-precision real 

p$92 Sin of real number 

P$93 Sin of double-precision real 

p$94 Cos of real number 


2-79 








Pascal-2 V2.1/RT-11 Programmer’s Guide 


Entry 

Point 

Description 

P$96 

P$96 

P$97 

P)98 

P$99 

P$100 

P$101 

P$102 

P$103 

P$104 

P)106 

P$106 

P$107 

P$108 

P$109 

P$ilO 

P$lll 

P$112 

P)113 

P$114 

P$115 

P$118 

P$117 

P$118 

P$119 

P$120 

P$121 

P$122 

P$123 

P$124 

P)125 

P$126 

P$127 

P$128 

P$129 

P$130 

P$131 

P$132 

P$133 

P$134 

P$13B 

Cos of double-precision real 

Atn (arctangent) of real number 

Atn of double-precision real 

Exp (exponential) of real number 

Exp of double-precision real 

Reserved 

Reserved 

Ln (natural logarithm) of real number 

Ln of double-precision real 

Reserved 

Reserved 

Time function -real 

Time function - double-precision real 
Round of real number 

Round of double-precision real 

Write boolean to standard file output 
Fortran interface 

Write boolean to text file 

Error reporting 

Reserved 

Reserved 

Unsigned integer multiplication simulation 
Real division simulation 

Unsigned integer division simulation 

Real multiplication simulation 

Unsigned integer mod 

Real subtraction simulation 

Reserved 

Real addition simulation 

Reserved 

Reserved 

Reserved 

Check for stack overflow 

Reserved 

Reserved 

Reserved 

Reserved 

Reserved 

Reserved 

Reserved 

Reserved 








Introduction to the Language Specification 

The Pascal-2 compiler processes the standard Pascal language, as described in the Pascal User 
Manual and Report [2nd edition], by Kathleen Jensen and Niklaus Wirth, published by Sprmger- 
Verlag, corrected printing of 1978. This language is more completely described in ISO Draft Proposal 
7185, ISO/TC 97/SC 5, dated August 12, 1982, which we call the “draft standard” hereafter. 

Compliance is Level 1: conformant array parameters are included. Pascal-2 includes the extensions 
detailed in this guide. This guide includes data on non-standard language features. This guide is not 
intended as a full language document. 

Syntax definitions in this specification use the notation described in Appendix C, Pascal-2 Syntax. 


Changes in the Standard 

Because you may not be familiar with all the changes to the Pascal language from Jensen and 
Wirth (1978) to the most recent draft of the standard (1982), this section outlines those changes and 
Pascal-2’s method of implementing them. 


‘For’ Statement Control Variables 

Variables that control a for statement must be simple variables, local to the routine in which the 
for statement is written. Originally, any variable could be used. 


File Declaration 

The standard states that the files input and output are automatically declared as global variables 
if they are mentioned in the program heading. Because program headings are optional in Pascal 2, 
input and output are declared as global variables in every Pascal-2 program. Thus, you cannot 
redefine input or output at the global level. In earlier versions of the language, the actual point of 

definition was undefined. 


Parameter Compatibility 

The compatibility rules for var parameters are now defined according to a restrictive rule, which 
requires the argument passed to have the same type as the formal parameter. Although the types 
must be the same, the type identifiers may differ. The appearance of a new type construct creates a 
new type. Previously, the rules for var parameters were undefined. 
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Procedure and Function Parameters 

The draft standard has changed the method of declaring procedure and function parameters. The 
new syntax provides a way of checking the parameters of these procedures and functions, thus 
reducing the likelihood of type errors. 

The syntax for a parameter list is changed to: 

parameter-list = “(” parameter-section {“;* parameter-section }*)* . 

parameter-section = ( [ “var* ] identifier identifier }“: n ( identifier 

| conformant-array-schema ) ) | procedure-heading | function-heading . 

A full procedure heading must be provided for any procedure or function declared as a parameter, 
and the procedure heading for any procedure or function passed as an actual parameter must match. 
For example: 

var 

K, L: integer; 

procedure P(procedure ft(I, J:integer)); 
begin 
ft(K. L); 
end; 

procedure PI(I,J: integer); 
begin 

writelnC'test of proc parameters', I, J); 
end; 

begin 
K := 1; 

L := 20; 

P(P1); 

end. 

The program issues the following output: 

test of proc parameters 1 20 

The draft standard does not allow a standard function to be used as a parameter for a function 
or procedure. To pass a standard function as a function or procedure argument, you must define 
a function that calls the standard function, then pass the user-defined function as the function or 
procedure argument. 


Conformant Array Parameters 


Normally, a procedure or function accepts an array parameter containing a fixed number of elements. 
The number of elements holding meaningful information may vary but the size of the array may 
not. If you need to pass arrays of different lengths, you have to declare and pass a general array 
that is as long as the longest possible array, and you must track the last element of each. Another 
approach is to write a separate procedure to handle each size of array, which is clearly inefficient. 


Use of conformant array parameters solves this problem. Conformant array parameters are formal 
parameters that allow you to write a general procedure or function that, at each activation, accepts 
array parameters of different size and with different lower and upper bounds. At activation, the 
upper and lower bounds of the conformant array parameter assume the upper and lower bounds of 
the passed parameter (the actual parameter). 
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Changes in the Standard 


The syntax for a conformant array parameter is: 

conformant-array-parameter-specification = 

[ “var” ] identifier-list “:” conformant-array-schema . 

conformant-array-schema = packed-conformant-array-schema 
| unpacked-conformant-array-schema . 

packed-conformant-array-schema = “packed array” 

“[” index-type-specification “]” “of” type-identifier . 

unpacked-conformant-array-schema = “array” “[” index-type-specification 

index-type-specification }“]” “ol” ( type-identifier | conformant-array-schema 

)• 

index-type-specification = bound-identifier “..” bound-identifier type-identifier . 

As the EBNF diagrams show, a conformant array schema may be either packed or unpacked. An 
unpacked conformant array may be nested within itself or within other conformant arrays (either 
packed or unpacked); if so, an abbreviated form may be used. In the example below, Mx is the 
conformant array parameter being used in Examp. Tl, T2 and T3 are data types. The two definitions 
are equivalent. Notice that the semicolon in the abbreviated form replaces of array [’ in the 
long form. 

procedure Examp(var Mx: array [Lbl..Ubl: Tl] of array [Lb2..Ub2: T2] of T3); 
or 

procedure ExampCvar Mx: array [Lbl..Ubl: Tl; Lb2..Ub2: T2] of T3); 

An array may be passed as a conformant array parameter if: 

• the elements have the same types, 

• the index types are compatible, and 

• the bounds are within the range specified by the parameter declaration. 

If two parameters are specified with a single conformant array schema, the actual parameter passed 
must have the same type. Also, a value conformant array may not be passed as a parameter to 
another procedure or function. 

The next example demonstrates the use of conformant array parameters. The formal parameter 
Arr is a conformant array parameter and takes the values of two different-sized arrays, First and 
Second. At the first activation of the function AddArray, the two elements of array First are added 
together to reach a sum. The next activation adds up the four elements of array Second and arrives 
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at a different sum, as shown in the output following the program listing. 

program Conform; 
war 

First: array [1..2] of integer; i two-element array > 

Second: array [0..3] of integer; { four-element array > 

Total: integer; 

function AddArray(war Arr: array [Lower. .Upper: integer] of integer): integer; 
▼ar 

I, Sum: integer; 
begin 

Sum := 0; 

for I := Lower to Upper do 
Sum := Sum + Arr[I]; 

AddArray := Sum 
end; 

begin 

First[1] := 5; First[2] := 9; 

Total := AddArray (First) ; -called with two-element array 

writeIn(‘Total for this array is: 1 , Total:5); 

Second[0] := 1; Second[1] := -31; Second[2] := 77; Second[3] := 15; 

Total := AddArray (Second) ; -called with four-element array 

writelnCTotal for this array is: 1 , Total:5) 
end. 

Running the program yields: 

Total for this array is: 14 -sum of elements of array First 

Total for this array is: 62 -sum of elements of array Second 

For a practical example of the use of conformant array parameters, see the source code of Pascal-2’s 
Dynamic String Package, in the file STRING.PAS. 

Literal Strings 

A literal string may not extend over more than a single line. Earlier standards were unclear on this 
point. The limitation allows better diagnostics for unterminated strings. 

‘Write,’ ‘Writeln’ of ‘Packed Array of Char’ 

r 

A write or writeln procedure call applied to a packed array of char writes only as many 
characters as the field-width parameter specifies. If the packed array of char exceeds the field- 
width, the string is truncated. The string is right-justified if the specified field width is longer than 
the packed array. If no field width is specified, a write or writeln writes as many characters as are 
in the string. 


C 
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Example: 

program Buff; 
rar 

Buffer: packed array [1..30] of char; 

BuffCount: integer; 

begin 

Buffer:= ‘This is a packed array of char 1 ; 
writeIn(Buffer); 

BuffCount := 6; 
writeln (Buffer: Buff Count) ; 
writeln(‘cutoff :3); 
write(‘shorter 1 :10) ; 
end. 

When executed, the program yields these results: 

This is a packed array of char 

This i 

cut 

shorter -—-note leading blanks 


Identifiers 

The initial character of an identifier must be an alphabetic character or a dollar sign. All other 
characters making up identifiers may be any combination of digits, letters, dollar signs or underbars. 
Identifiers may be of any length; all characters are significant. Lower-case characters are interpreted 
in the same way as upper-case characters. For example, name, Name, NamE, and NAME are equivalent. 
See “Syntax Extensions” for details on the the use of the non-standard dollar sign and under bar in 
identifiers. 

Alternate Symbol Representations 

The standard now defines alternate representations for symbols that are unavailable in some charac¬ 
ter sets. These are: 

Standard Symbol Alternate Symbol 

* or t 0 (‘at* sign) 

{ (* 

> *) 

[ (. 

] •) 

The alternate comment delimiters are equivalent to the standard comment delimiters, and a comment 
may open with one type of delimiter and close with the other. Comments may not be nested. 

Examples: 

(* This is a valid comment > 

{ This is (* not *) a valid comment > 
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Implementation Definitions 

This section provides details and characteristics of implementation-defined elements of Pascal-2. 


Standard Type ‘Integer* 

The predefined identifier maxint has the value 32787. 

The standard type integer has the range (-32787..32787). An unsigned (extended-range) integer 
may be defined with the range 0..65535. See “Unsigned Integer Conversion* in the Programmer’s 
Guide. 


Standard Type ‘Real* 


A real variable has the standard PDP-11 single-precision or double-precision floating-point struc¬ 
ture, with magnitude in the range 1E-38..1E+38. Single-precision values give approximately 7 
decimal digit precision; extended (double-precision) values give approximately 15-diglt precision. 
Arithmetic overflow is detected for all real operations, but underflow is ignored and returns a result 
of zero. 


The standard transcendental routines are accurate to 6 decimal digits in single precision and to 15 
decimal digits in extended precision. 

Standard Type ‘Char’ 


The draft standard does not define the character set to be used internally to represent char. Pascal-2 
uses 8-bit characters, allowing the use of the extended version of the ASCII character set, rather 
than 7-bit characters to represent the standard ASCII character set. The most significant bit is “off* 
unless used with extended character sets. Grd(char) is in the range 0..255. 

Programs that calculate bit or byte offsets into a packed structure should treat a character as 8 bits, 
not 7; and storage size is the same for characters in either packed or unpacked structures. 

Standard Type ‘Text’ 


The standard type text is a file type with components of type char. Text is implemented as a file 
of 8-bit ASCfi characters. 


‘Set’ Types 

Pascal-2 limits a set to a maximum of 258 elements. The lower and upper bounds must lie in the 
range 0..255, e.g., set of 4. .9. The declaration set of integer is equivalent to the declaration 
set of 0. .255. See “Undetected Errors* for restrictions on the checking of integer sets. 
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I/O Definitions 

The following table summarizes the default field widths used when values are written to a text file: 

Value Type Field Width 
integer 7 

real 13 

boolean 5 

The floating-point representation of a real number includes the sign of the number (a space for 
positive numbers and a for negative numbers), the real number in scientific notation, an upper¬ 
case E signifying exponential notation, the sign of the exponent (‘+* or ‘-’), and a two-digit exponent. 
For example, the real number —105.39 prints as -1.053900E+02. 

Boolean values are written in upper case (TRUE, FALSE). In the five-character default field, the value 
TRUE is right-justified, with a leading blank before the *T\ 

The procedure page (F) inserts a form feed (page eject) into the file specified by the required file 
argument. Calling page(F) with data in the file buffer executes writeln(F), which writes the 
remainder of the buffer, and write(F.chr(12)), which writes the form-feed character. Calling 
page (F) with an empty file buffer results in a page eject only. 

If associated with the standard input file (the terminal), reset (input) performs the equivalent 
of a readln, but otherwise has no effect; in the same way, rewrite (output) prints any incom¬ 
plete line, but otherwise has no effect. Reset (output) or rewrite (input) produces an error mes¬ 
sage. See “External File Access” for details on the use of the extended form of reset (input) or 
rewrite (output). 
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Syntax Extensions 

This section describes Pascal-2 extensions to the syntax of standard Pascal. 


Identifiers 

The character $ (dollar sign) is allowed in an identifier anywhere an alphabetic character is allowed. 
The character _ (underbar) is allowed anywhere a numeric character is allowed. For example, the 
identifier _ABC is not valid because it begins with an underbar. The following are legal identifiers: 

8ystom$name 
$$file 

this_is_a_loiig_identifier 
This_Is.Also_Legal 


Program Heading 

In standard Pascal, the program heading is required, and the parameters define the external files to 
be used: 

program Test (input, output, File3); 

In Pascal-2, the program heading and parameters are not required. If present, they will be checked 
for proper syntax. The file parameters will otherwise be ignored. Input and output are automatically 
declared file variables. Every other external file must be specified by an additional parameter allowed 
in the standard procedures reset and rewrite. See “External File Access” under “I/O Support 
Extensions” for details. 

Though not required, inclusion of the program name on the program statement is still a good practice 
because it names the object module for main programs and external modules. Further, the program 
name is used to name the psect when the own compilation switch is specified. 


Declaration Order 

The declaration sections label, const, type, var, procedure, and function may be interleaved 
as desired at the global level of a program. Const and type may be interleaved at other levels. 
This extension is useful for source module inclusion and structured constant definitions as described 
below. Any number of declaration sections of each type may be present. An identifier still must be 
defined before the identifier is used in any other way. 

‘^Include’ Lexical Directive 

A special directive allows separate text files to be included within a program. The contents of the 
separate file are inserted into the program at whatever point the {(include directive occurs. Included 
files may themselves contain {(include directives, nested to a maximum of seven levels. 

The syntax for the {(include directive is: 

^include 1 file-name-string 1 ; 

The file-name-string must contain at least the name of the file; if no file extension is specified, .PAS is 
assumed. In addition to the file name and extension, file-name-string may contain such information 
as the logical device name and disk volume number of the file. 

The single quotes ( 1 ... 1 ) enclosing file-name-string are optional. This syntax provides compatibility 
with other implementations of Pascal-2 that allow file version numbers. 
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Examples: 

Xiaclad* hdr; 

Xiaclnd* 'aathdr.pas'; 
linelade tarn.doc; 

Unclad# ’sy:kfll'; 

See the Programmer’s Guide for details. 


‘%Pa*e’ Lexical Directive 

The Ipage directive causes a page break (form feed) ia the listing file immediately following the line 
on which the Ipv directive is placed. The Ipage directive itself is printed in the listing file on the 
last listed line of the page preceding the page eject. The ending semicolon is optional. 

v 

‘External* and 'NonPase&T Directives 

Similar to the forward standard directive, the external directive distinguishes a particular Pascal 
procedure or function that is separate from the module that invokes it. An external procedure must 
be declared at the global level. If the body of an external procedure or function does not appear 
in a compilation, it is assumed that the body will be in another object module. If the body of the 
external procedure does appear, its name will be made available in the object module for reference 
by other modules. References to the external procedure are resolved at link time. 

Limitations of the object module structure require that external names be distinct within the first 
six characters. The underbar cannot be expressed in the object module format and is replaced by a 
period in the external name. No type checking is done for parameters of an external routine. 

The aonpancal directive is used instead of external if the external procedure is written in a 
language other than Pascal, lonpancal creates an interface between the Pascal-2 calling sequence 
of the program or module doing the calling and the DEC calling sequence required by non-Pascal 
external routine, usually a FORTRAN or MACRO-11 module. The aonpancal directive makes use 
of the convention of having register B5 point to a list of parameters. All parameters are passed 
by reference, so only var parameters may be used. MACRO-11 routines written with the Pascal-2 
PASMAC utility must be declared as external rather than aonpancal, because PASMAC simulates 
the Pascal-2 calling sequence. 

See also “External Modules” in the Programmer’s Guide for details. 

Structured Constanta 

The syntax for constant definitions is extended to allow you to specify constants in record and array 
types. Under the standard, arrays or records cannot be assigned values in the constants declarations; 
each element must be assigned a value in the program body with an assignment statement. The 
structured-constants language extension eliminates the need to use assignment statements to assign 
values to constants of type array or record. See the examples following for a comparison of 
structured constants declarations versus standard constant declarations. 


3-9 


Updated January IBM 





Pascal-2 V2.1/RT-11 Language Specification 


The formal syntax for structured constants is: 
structured-constant ™ 

s tract ared-tjrpe-idcntiBer constznt-component-list . 
const Ant-component-list =» “(” constant-component {*,’ constant-component }“)" . 
constant-component ■■ constant | constint-component-list . 

where 

stractared-tjpe-identiBer 

Is a data type with an array or record structure. All of the components of that 
structure must be of simple types, array types, or record types. 

constant-component 

Must correspond one to one with the component of the structured (array or record) 
type, and each constant-component must be a constant of the same type as the 
corresponding structure component. An access to the structure component returns 
the value of the constant-component. If the structure component is of a structured 
type, only the corresponding constant-component-iist must be provided, declared with 
the proper syntax. 

The following are valid declarations. Note that the data types needed by the structured constant 
must be declared before the structured constants. 

typa 

51 « packed array [1..4] of char; 

52 * record 
String: SI; 

end; 

const 

Cl • SlCa*. 'b*. 'c*. 'd'); 

C2 « S2('abcd'); 

The structured-tjpc-identiBer for individual components need not be provided. For variant records 
(even those without a tag-field) a tag value must be provided in the constant-component-list. 

Constants used as components in a constant-component-list appear between nested levels of paren¬ 
theses. If an element is another structured type, a constant type of the same structure may appear or 
its elements may be set individually between inner parentheses. However, you may not use structured 
constants or their individual elements as can* labels; can* labels must be of simple type. 

Examples of Structured Constants 

Three examples are presented showing several uses of structured constants. The first example 
illustrates the nesting of parentheses in the structured constant declarations. The second example 
compares the standard’s method of declaring record or array constants with the structured constant 
method. The third example shows the correct way to declare multidimensional arrays of constants. 

The structured constant Workers in the following declarations contains three levels of parentheses: 
the first for the array structure; the next for the outer record; the last for the pay information. 
The fourth constant in the array, however, for Maxine, contains a structured element that is set by 
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reference to a constant of the same type with no further inner parentheses, 
type 

Compensation = (Paid. Unpaid); 

Paytype = Record 

Title : (Clerk, Indian, Chief, President); 
case Compensation of 
Paid: (Rate: real); 

Unpaid: (); 
end; 

Enployeetable = array[1..4] of record 
Name : packed array[1..10] of char; 

Payinfo : Paytype; 
end; 

const 

Canchief = Paytype (Chief, Paid, 6.85); — note redefinition for Maxine 

Yorkers = Employeetable( 

('Charlie ', (Clerk, Paid. 3.40)), 

('Samuel ', (Indian, Paid, 5.25)), 

( 1 Edvard ', (President, Unpaid)), 

('Maxine ', Conchief) -note condensed form 

); 

To illustrate the efficiency and ease of use of structured constants, we present a comparison of 
the standard method of declaring constants for arrays and records versus the structured constants 
method. The program used in the comparison — DayCalc — calculates the day of the week for any 
date. The declarations below are those required to declare two arrays of constants, MonthName and 
DayOff set. Note that the type declarations are identical in both cases. The declaration of other 
data types, constants and variables have been omitted. 

To conform to the standard, constants in arrays and records must be declared and assigned values as 
shown below. This method requires many more statements than the equivalent structured constants 
declarations, provided following the standard example. 

program DayCalc; { use of standard constant declarations } 

type 

Month = (Jan, Feb. Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec, 
Unknown); 

Name = packed array [1..3] of char; 

NameList = array [Month] of Name; 

DayOffsetList = packed array [Month] of 0..6; 

var 

MonthName: NameList; 

DayOffset: DayOffsetList; 


{ Text for name of month > 
< Day mod 7 > 
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begin { DayCalc > 

MonthName[Jan] := 1 j an 1 
MonthName[Apr] := 1 apr 1 
MonthName[Jnl] := 1 j ul 1 
MonthName [Oct] := 'oct' 
MonthName[Unknown] := 1 


; MonthName [Feb] 

:= 'feb'; 

; MonthName[May] 

:= 'may'; 

; MonthName [Aug] 

:= 'aug'; 

; MonthName [Not] 

:= 'noT*; 

???'; 



MonthName [Mar] 

:= 'mar 1 

MonthName [Jun] 

:= 'jun 1 

MonthName [Sep] 

:= 'sep 1 

MonthName [Dec] 

:= 'dec 1 


DayOffset[Jan] := 0; DayOffset[Feb] := 3; DayOffset [Mar] := 3; 

DayOffset[Apr] := 6; DayOffset[May] : = 1; DayOffset[Jun] := 4; 

DayOffset[Jnl] := 6; DayOffset[Aug] := 2; DayOffset [Sep] := 5; 

DayOffset[Oct] := 0; DayOffset [Not] := 3; DayOffset[Dec] := 5; 

DayOffset[Unknown] := 0; 

: - rest of program goes here 


With structured constants, on the other hand, your code is much shorter and easier to maintain 
than with the standard method. The only drawbacks are that the program is non-standard and is 
not necessarily portable to other Pascal implementations. 

program DayCalc; { use of structured constants > 

type 

Month = (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Not, Dec, 
Unknown); 

DayOffsetList = packed array [Month] of 0..6; 

Name = packed array [1..3] of char; 

NameList = array [Month] of Name; 


const 

MonthName = NameList C * j an 1 , 'feb 1 , 'mar 1 , •apr 1 , 'may 1 , 'jun 1 , 

'jul 1 , 'aug 1 , 'sep', 'oct', 'now 1 , 'dec 1 , •???•); 
DayOffset = Day0ffsetList(0, 3, 3, 6, 1, 4, 6, 2, 5, 0, 3, 5, 0); 

: - rest of declarations and program body goes here 

Multidimensional arrays of constants, such as the two-dimensional array below, can be declared as 
in the following program. This program prints the elements of the two-dimensional array Table in 
the order they are stored. 

program TwoDimensions; 
const 

MaxElem = 3; 


type 

CharTable = packed array [1..MaxElem, 1..MaxElem] of char; 
const 

Table = CharTable(( 1 x*, 

('a', 

('p*. 

var 

I, J: integer; 


'7'. 'z'). 
'b\ 'c'). 
'd'. 'q')); 
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begin { TwoDimensions > 

for I := 1 to MaxElem do 
for J := 1 to MaxElem do 
write(Table[I,J], 1 '); 

write In; 

end. < TwoDimensions > 

Running this program yields: 

xyzabcpdq 

Default Case Label (‘Otherwise*) 

A default statement can be included in a case statement according to the following syntax: 

case-statement = "case" case-index “of* [ case-element {“;* case-element }] 

[“;*][ “otherwise* default-statement [*;*]] “end* . 

The default statement, which immediately follows the otherwise clause, is executed if no case label 
matches the value of the case-index. A special note on otherwise syntax: In contrast to the case 
label, which requires a colon, the otherwise clause must not contain a colon or a compilation error 
results. 

Example: 

case I of 

1: Ch := •:•; 

9: Ch := 

otherwise Ch := , * 1 ; 
end; 

The list case-element is optional, so the following example is valid. 

case I of 
otherwise I := 1; 
end; 
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I/O Support Extensions 

I/O support extensions provide the Pascal-2 programmer with additional control of the interface to 
the operating system. 

External File Access 

The standard procedures reset, for opening an existing file, and rewrite, for creating a new file, 
have been extended to accept optional arguments that give Pascal-2 programs the ability to associate 
internal file variables with external file or device specifications. The syntax is as follows: 

rewrite (file-variable, device-or-fiie-name, default-values, Ole-status); 
reset (file- variable, device-or-Ole-name, default-values. Ole-status) ; 

where 

Ole-variable 

is a standard Pascal file variable. 
device-or-Ole-name 

specifies the name of an external file with which the file variable is to be associated. 
This parameter, which may be a device or file name specification, must be a string 
type and may be either a literal string or a variable. 

default-values 

is also of a string type, providing default values for any file fields not provided in 
the file name, including default file options. 

Ole-stat us 

is an integer variable that is primarily used to return a special status code if the 
file cannot be opened; this code allows a program to recover from an otherwise fa¬ 
tal error. The fourth parameter also may be used to determine the number of blocks 
allocated to a file or to specify the number of blocks to allocated to a new file. 
These uses are explained in detail below. 

Commas must separate any optional parameters used; a comma must be included to mark off an 
omitted parameter but need not follow the last included parameter. The following example opens a 
file for direct access and skips the file-name parameter, indicating a temporary file. 

rewrite(FI, , '/seek*); 

See “Random Access to Data Files” for details on the /seek switch, and see “I/O Control Switches” 
in the Programmer’s Guide for details on the use of other file switches. 

The optional parameters may be used to redirect the standard files input or output, which by 
default are file variables associated with the standard terminal input or output devices, respectively. 
The next example redirects output from the terminal to the line printer. 

rewrite(output, 1 LP: 1 ); 

Normally, an I/O error with reset or rewrite causes the support library to trap the error, terminate 
the program, and print an error message and procedure walkback. The fourth parameter may be 
used to return control to the program. If the fourth parameter is specified and an I/O error occurs, 
the support library sets the value of the fourth parameter to -1 and returns control to the program. 
You must check the value returned by the fourth parameter and specify what action to take if an 
error occurs. For example: 

reset(infile, Filename, '.1st', status); 

if status = -1 then UserProcessError - 

else ContinueUserProgram; 
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Or you may use the predefined functions in the support library to initiate run-time diagnostics. 
These functions check the status of the fourth parameter and respond accordingly. See Run-Time 
Error Reporting* in the Programmer’s Guide. Either way, you must check the value of the fourth 
parameter each time you use it; otherwise, the program continues but may act unpredict ably. 

If the file is successfully opened, the fourth parameter returns the number of blocks allocated to the 
file. In addition, the fourth parameter may be used with rewrite to specify the number of blocks 
to be initially allocated to the file. When the size of the file is known in advance, this specification 
allows efficient space allocation by the operating system. If the file does not actually occupy the 
number of blocks specified, however, the operating system will truncate the file to the number of 
blocks needed. In turn, the value of the fourth parameter may be checked after a rewrite to be 
certain that the file was allocated the number of blocks you wished. 

Two values for the fourth parameter have special meaning on RT-11. A value of 0 indicates that the 
file should be allocated one-half of the largest contiguous space. A value of -1 specifies that you want 
all contiguous space allocated to the file. In both cases, the value upon return is the amount of space 
actually given to the file or is -1 if an error occurred in opening the file. If the fourth parameter is 
absent, the file size is determined by the operating system and expands dynamically. Examples: 

reset(f, 'test 1 , 1 .pas*, size) ; -— assumes default of .PAS 

write In (size); -- returns the size of the file in blocks 

size := 64; 

rewrite (output, outstr, '.lis'. size) ; -file initially allocated 64 blocks 


‘Close’ Procedure 

The close predefined procedure indicates that its file parameter is no longer in use; close will 
reclaim buffer memory. Further access to the file is prohibited until reset or rewrite is used. 
Files are automatically closed upon program termination, or when they appear in another reset or 
rewrite; close allows files to be closed manually when it is necessary to reclaim buffer space before 
then. In addition, a file variable local to a procedure or function is automatically closed when that 
function or procedure terminates. See the sample program Alphas in the next section for implicit 
uses of close. 


Random Access to Data Files (‘Seek’) 

Pascal-2 includes the seek predefined procedure to allow direct access (random access) to data 
files opened with the /seek file control switch. The seek procedure requires two parameters: a file 
variable of the file to be accessed, declared as a file of char or other file type (but not of type 
text); and an integer record number (records in the file are numbered sequentially beginning with 
1). After the seek call, the specified record is available in the file buffer if it exists; otherwise eof is 
set to indicate that the record is not available. 

Seek also enables both reading and writing on the same file for in-place record updates. Put is 
required if the file buffer variable is to be written to the file. Get and put may be mixed with seek 
for sequential access, because the internal record pointer is updated after each get and put. See the 
example following for the use of put and seek. 

After the file pointer is positioned by seek, both read and write as well as get and put may be 
performed. Read and write transfer data between the user variable and the file; get and put transfer 
data between the file buffer variable and the file. The following sequences may be used for direct 
access. 

seek(F,I); read(F.V); { read record I into V > 
seek(F.I); write(F.V); { write record I from V > 
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Example: 

program Alphas; 

▼ar 

C: char; 

F: file of char; 


begin 

rewrite(F, 1 alpha,txt 1 ); 
for C := 'a 1 to % z l do 
write(F, C); 

reset(F, 1 alpha.txt/seek 1 ); 
seekCF, 4); 
writeln(F~); 

F- := 'Z*; 

put(F); 

end. - 


{ open F for writing > 

{ write letters of the alphabet to F > 
{ close and reopen F for seeking > 

{ read record containing 'd 1 > 

{ write a 'd* to output > 

{ *d* becomes 'z 1 > 

{ write 'z' to F in place of 'd* > 
-F closed automatically 


As the program shows, the /seek file control switch must be used with reset or rewrite if the 
seek procedure is to be used to access the file. See “I/O Control Switches* in the Programmer’s 
Guide for details. 

At run-time, the character *d’ is written to the terminal. After program termination, the file 
ALPHA.TXT contains: 

abczefghijklmnopqrsturwxyz -z takes the place of d 


Seek does not work on text files. For simulated random access on text files, you must use the getpos 
and setpos external procedures. See “Random Access to ‘Text’ Files* in the Programmer’s Guide. 


String Input (‘Read’ and ‘Readln’) 

A character string is a packed array [1. .n] of char. The read and readln procedures may be 
used to read variables of string types. Characters are read until the variable is filled. If eoln becomes 
true, the remainder of the string is filled with spaces. See “The Dynamic String Package* in the 
Utilities Guide for more sophisticated ways to read and manipulate strings. 


‘Break’ Procedure 

For efficiency, Pascal-2 buffers transmitted output data. Break(F) forces the actual transmission 
of data from a partially filled buffer of file F. This can be useful with interactive terminals or to 
guarantee actual transmission of data to a shared disk file. 

Octal Output 

In an integer write procedure call, a negative field-width specification will represent characters in 
octal (base 8). 

Example: 

write(I:-5); { Display octal value of I > 
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Real Number Formatting 

If the second formatting field is negative, a real number is printed in scientific notation. The number 
of digits to the right of the decimal point is the number specified in the second field. (The standard 
allows you to specify an integer constant or an integer expression in either formatting field.) 

For example, 

vrit«(B:20:-6); 

prints B with one digit to the left of the decimal point and five digits to the right, followed by an 
upper-case E, a sign character or and two digits signifying the exponent. The entire number 
is right-justified in a 20-character field. 

If B has the value -367.2, the statement vritolaCB-* ,B:20:-5) prints: 

B« -3.672002*02 
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Low-Level Interface 

This section describes Pascal-2 extensions that are useful to programmers needing access to machine- 
dependent characteristics. 


Boolean Operators on Integer 

The boolean operators and, or, and not may be applied to operands of Integer or Integer subrange 
type. The not operator is always applied first. The operators produce a 16-bit result of Integer 
type. 


Nondecimal Integer Constants 

Nondecimal integer constants may be specified in two forms of notation. In the preferred form, the 
nondecimal value is written as shown: 

nondecim&l-intcger-coostznt = digit-sequence “#” fiexadecimaJ-d/git-seqaence. 

where digit-sequence is the radix, or base, of the number, in the range 2.. 16. The number following 
the cross-hatch character '#’ is any number represented in base digit-seqnence notation. The *#’ 
symbol is required regardless of base. For example, the decimal value 255 is written M377 for base 
8 and 16BFF for base 16. Also, the redundant form 10#255 is valid for the decimal value 255. 

Pascal-2 supports another form of notation as a special case. Octal (base 8) notation for integer 
constants is signified by the suffix “B" (upper or lower case), so that S77B and 377b are the same 
value as 255 decimal. 


Extended-Rangn Arithmetic 

The normal range of Integer variables in Pascat-2 is —32767..32767, but you also may declare 
integer types in the extended range of 0..65535. A variable with an upper limit greater than 32767 
is called an extended-range or “unsigned” variable. Normal arithmetic operations, with the exception 
of division and modulo, are performed on extended-range variables. Comparisons and division are 
signed. An integer value may be assigned to an extended value, being converted as a bit pattern. If 
the value being assigned is negative, the error is not trapped at run-time, since there is no way for 
the compiler to tell the difference between a negative value and an extended-range value. The same 
6ort of implicit transformation is true when an extended value is assigned to an integer variable. No 
conversion is done for constants. 

The following sample program illustrates the way Pascal-2 handles extended-range numbers. Within 
the repeat util statement, the program reads an integer then prints it as an unsigned integer 
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and as a signed integer. The external procedure Ovrlte is provided in the section on “Unsigned 
Integer Conversion* in the Programmer’s Guide. 

prograa BigluberTest; 
type 

assigned « 0..66535; 
var 

Blgltaber: Unsigned; 

procedure Ovrlte(I: Unsigned; Vldth: Integer); 
external; < procedure to vrlte an unsigned Integer to output ) 

begin { BlglunberTest > 
repeat 

vrlte('Enter an Integer: '); 

rendla(BlgBunber); 

vrlteC Unsigned. BICIUMBEB > '); 

nvrlte(BlgBunber.1); vrltela; 

vritelaO Signed. BICBUMBEB • BlgBunber:1); 

vrlteln; 

until false < forever ); 
end. { BlgBunberTest ) 

The program is executed, producing the following results. As mentioned earlier, the allowable range 
of values for the integer BlgBunber is —32767..32767.The final entry — in fact, any value outside the 
range of possible integers — is an invalid value for an integer, halting the program with a walkback 
(unless valkback is disabled). 

Eater an Integer: ~1 
Unsigned. BICBUMBEB » 65535 
Signed. BICBUMBEB « -1 

Enter an Integer: -32767 
Unsigned. BICBUMBEB » 32769 
Signed. BICIUMBEB » -32767 

Enter an integer: 32767 
Unsigned. BICBUMBEB * 32767 
Signed. BICBUMBEB * 32767 

Eater an integer: -6566 
Unsigned. BICBUMBEB = 59981 
Signed. BICBUMBEB * -5655 

Eater an Integer: 6556 
Unsigned. BICBUMBEB « 6555 
Signed. BICBUMBEB * 6565 

Eater an Integer: 66635 

PASCAL—I/O error at user PC* 10S0B 
Illegal value for Integer 

Error occurred at line 16 la prograa blgnnnbertest 
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See “Unsigned Integer Conversion” in the Programmer’s Guide for Pascal routines that perform 
extended-range arithmetic and extended-range output. 

"Origin” Declaration 

A variable can be declared to have a particular address in the I/O page or system area with the 
following syntax: 

var-dec/aratioa = rar-e/ement var-e/ement}”:* type . 
var-e/ement = identifier [“origin” constant!. 

The constant in the above syntax must have an integer value. A variable so specified has the address 
given by the integer following origin. This must be in the system space 0. .7778 or in the I/O page 
1600008..177777B. 

The following example demonstrates the use of origin, plus the use of the ref and size functions. 
See “Ref Function” and “Size and Bitsize Functions” for more details on those routines. The example 
controls a mythical device. The procedure ReadData sets up the device’s control registers and initiates 
a transfer from the device into the task’s memory. This example is specific to a machine without 
memory management hardware, such as a small RT-11 system. 

program Device; { exanple of dovlco control > 


const 


< ready flag > 


Ready * 2008; 
ReadBuffer * 1; 



type 

Buffer * packed array [1..100] of char; 

BufferPolater * ‘Buffer; 

var 

StatusReglster origin 177316B: integer; 

CoatrolReglster origin 177314B: integer; 

BufferAddress origin 1773128: Buffor.Pointer; 

ByteCount origin 1773108: integer; 

Data: Buffer; { kolde data from device > 

procedure ReadData; 
begin { ReadData > 

BufferAddress :■ ref(Data); { Address for DMA xfer ) 

ByteCount := slze(Buffer); { size of buffer ) 

CoatrolReglster :* ReadBuffer; ( start transfer ) 

< Walt for device to coaplete transfer > 
vhlle (StatusReglster and Ready) * 0 do (vait); 
end; { ReadData ) 

begin { Device > 

ReadData; 

end. < Device ) 
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‘Ref’ Function 

The ref function, with a variable argument of type T, produces a pointer to that variable with result 
type “T (pointer to T). The dispose routine cannot always detect attempts to dispose of a pointer 
generated with this function, and you should not try to do so. 

See the example under “Origin Declaration* and under “Loophole Function’ for uses of ref. 


‘Sise’ and ‘Bitsise’ Functions 

Two functions, size and bitsize, give the programmer information on the space allocated for 
values of different types. The functions have a single argument, a type identifier. 

The function size returns the number of bytes that would be allocated for an object of that type 
by normal variable allocation. The function bitsize returns the number of bits that would be 
allocated for an object of that type as a component of a packed record. This is the actual number, 
of bits required to hold the value. 

For example, suppose you had declared atype Subrange a 0. .16 and called the functiomr .Is. wd 
bitsize, as in the following example program. The results tell you that two bytes and four bits are 
allocated for the argument in question. 

program SizeBitsize; 
type 

Subrange = 0..15; 


begin 

writeln(size(Subrange)); 
writeIn(bitsize(Subrange)); 
end. 


The program yields these results: 

2 _________2 bytes are allocated 

_ _____ 4 bits are allocated 

4 

These functions are primarily useful when you are interfacing with the operating system or with 
hardware functions. 

See “Origin Declaration” for another example of size. 


‘Loophole’ Function 

The loophole function, by providing a controlled escape from Pascal type rules, allows you to assign 
variables of one type to a variable of a different type. One use, shown in the DuapMenory example 
following, is to convert a pointer type to an integer type, perhaps to perform pomterarithmet^ 
The Pascal-2 Debugger, which examines program data, uses loophole to look at the stack and 

compute the values of pointers. 

The invocation of loophole requires two parameters: 

loophole ( returned-type, expression-to~convert) ; 

where returned-type is an identifier specifying the data type to be returned by loophole, and 
expression-to-convert is an expression of a “compatible” type that is converted to returned-type. In 
this context two types are considered compatible only if they require the same amount of storage 
(see “Storage Allocation” in the Programmer’s Guide), or if they are both non-real scalar types. 
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The result of the loophole function is the bit pattern of the second argument, expressed as a value 
of the type specified in the first argument. 

The following program illustrates the compatibility rules that govern the use of loophole. The 
"gram «<*?<*. • r.1 number to an equivalent two-word array of intesera r«pre*n^ tte »o 
word, used to store the real value, then coerces the Ivor word array back mto a real 
program then coerces an integer in the rang. 0..4 to a acalar of type Car, then coerce, the scalar 
back to an integer. The loophole (integer. S) is equivalent to the statement I .-or ( ). 


program Coerce; 


type 

Realequiv = array [0..1] of integer; 

Car = (Buick, VI, Datsun. Chevy. BUI); { scalar type > 


var 

Re: Realequiv; 

R: real; 

S: Car; { scalar > 
I: integer; 


begin ( Coerce > 

write('Enter a Real number: '); 

Re^^loophole (Realequiv . R); < coerces real into 2-wd «r*7 integers > 
vrltelnCRe = '. Re[0]:-8. Re[l]:-8); { 2-vd array printed in octal > 

R := loophole(Real. Re); ( coerces 2-wd array back to real > 
writelnC*R = 1 , R) ; 

writeC'Enter an integer in range 0..4: *); 

readln(I); _ x 

s := loophole (Car. I); <■ coerces integer to scalar > 

write( 1 S = 1 ); 

case S of { writes the scalar value > 

Buick: writelnCBuick') ; 

VI: writelnCVI'); 

Datsun: writeIn( 1 Datsun'); 

Chevy: writeln('Chevy'); 

BUI: writeIn('BMW'); 

end; { case } « 

I := loophole (integer. S); { coerces scalar back to integer > 

writelnC*I =*, I); 
end. { Coerce > 

When executed, the program yields these results: 

Enter a Real number: 21567 ^9 ... v fo^j .1 

g e _ 43650 77716 -octal representation of real number (2 words) 

R = 2.166790E+04 

Enter an integer in range 0..4: 2 

S = Datsun 

I = 2 

The only other method of type coercion is to declare a record with variants, using the fact that the 
compiler Overlay* storage ^different variants. This method makes the same kind of assumptions 
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as the loophole function about the compiler’s allocation of memory and machine’s architecture. 
However, the loophole function has several advantages over variant records: 

• No assumption need be made about field allocation in a variant record. 

• The compiler checks that the different types are the same size. 

• The bypassing of type checking rules is clearly marked (the compiler will flag loophole if the 
(standard switch is set). Also, if the code is used with a compiler other than Pascal-2, that 
compiler should mark loophole as an error, and appropriate changes can be made to the code. 
With variant records, the code might compile but not work. 

The following sample program uses the loophole function to perform arithmetic on pointers so that 
a block of the task’s memory can be printed. 

program MDump; 
type 

ford = 0..65535; 

procedure DumpMemory(Start, Finish: Word); 
type 

Pointer = *integer; 
var 

P: Pointer; 

begin i Dump Memory > 

P := loophole(Pointer, Start); 

while loophole(ford, P) <= Finish do begin 

writelnCloophole(integer, P): -6, 1 : 1 , P~: -6); 

P := loophole(Pointer, loophole(ford, P) +2); 
end; 

end; { Dump Memory > 

begin { MDump > 

DumpMemory(1210B, 1220B); 
end. { MDump > 

The program yields these results: 

1210 : 6 
1212: 101032 
1214: 10546 

1216: 12746 

1220: 177772 

The next example shows a method to print the address of a variable of any type. The program creates 
a pointer to the variable, coerces the pointer type into the type used in procedure IriteAddross, 
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and prints out the address. 

program PrintAddress; 


type 

U_Pointer 


0..65535; < unsigned integers > 


rar 

C: char; 

R: real; 

Cptr; "char; 

Uptr: U_Pointer; 

P_Integer; “integer; 


procedure WriteAddxess(A; U_Pointer), 

begin x 

writeIn(A; -7); {octal value of address} 

end; 

begin { PrintAddress } 

Uptr := loophoieCU^o^er^^r^coerce pointer into an address > 

nrsi.-- > 

newCP.Integer); 

(O.P.lnt.r. <prft poi.fr f ff«.r > 

end. { PrintAddress > 


The program yields these results: 

11106 

11110 

31436 


4 


/ 
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Non-Standard Language Elements 


Program Parameters 

According to the standard, parameters supplied in the program header indicate external files. 
Further, the input and output files must appear in the program header if they are used in the 
program. The input and output files are always defined at the global level and may not be redeclared 
at that level. 

With Pascal-2, the program header is not required, and any program parameters are entirely ignored 
(see “Program Heading” under “Syntax Extensions”). External files are referenced instead by an 
extended form of reset and rewrite using a second parameter (a string) giving the external filename 
(see “External File Access” under “I/O Support Extensions”). 

Directives 

The draft standard treats standard directives such as forward as neither an identifier nor a reserved 
word. Pascal-2 treats the directives forward, external, nonpascal as reserved words. An identifier 
cannot have the same name as one of these directives. 


‘Mod’ of Negative Numbers 

The draft standard states that the divisor must be positive and the operator nod must have a 
non-negative result. That is, 

0 < /mod/ < / 

The Pascal-2 compiler generates a divide instruction that gives a negative result if I is negative. 
The standard result can be generated by: 

Result := I mod J; 

if Result < 0 then Result := Result + J; 


‘Eof’ Not Accurate For Binary Files 

A RT-11 file structure is a sequence of 512-byte blocks. A file containing short records may actually 
end in the middle of a block, but no information is available as to the end of valid data in the last 
block, so the eof standard function should not be relied upon as accurate. Another method, such 
as a sentinel record or a record count, should be used to indicate the end of usable data. 

Eof is correctly indicated for text files. 

Structured Types as Function Return Values 

Under the standard, functions can return simple data types only (e.g., integer, real, char). With 
Pascal-2, functions may return structured data types such as record, array and set types in 
addition to simple types. For example, the function KeySort, of structured type, is declared as: 

function KeySortCKey: KeyType) : StructType; 
where StructType is the structured data type of the return value of KeySort. 
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Additional Predefined Functions and Procedures 

The Pascal-2 system includes predefined functions and ^Mssection describes 

Most of these are grouped according to function in other sections in this gmae. ini 

function. *nd Proc^e. uot othsns.se descnbed. 

Because these procedure, and functions are '“°™the other procedure! 

be predefined in future relemms but for no. 

must be declared as an external procedure. 

Procedure ‘Delete’ 

The predefined delete procedure^allowsthe dele*™ of ^dekted. Invoke the procedure 
program. Delete accepts one argument, the me vanaDi 
with a statement similar to the following: 

delete(F); 

Internally, this procedure Cos* and delete, the ^ 

discussion of the rename procedure. 

Procedure ‘Rename’ 

The predefined procedure S‘tt ffl^£bT5“e 

55 ^”»d JJl«t Z he uS file name o, the net, file. Inuohe the procedure 
a statement similar to the followup__ f ^ 


rename(F, 'newfil.tit 1 )i 

or: 

NewF := 1 newfil.tit 1 ; 
rename (F, NewF); 


renames F to NEWFIL.TXT 


S “tTal file name. For example, to chan*, the extensmn only, one 

a statement similar tothls: _ ^ ^ MAC „ the ne. pension 

rename CF , •mac j» 

The original file must be open (yin r.n.t) before r.nane may be c^.ed on the filn. Tbs rennmed file 
is automatically closed upon completion of the operation. 

- - 
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“good* reports are written to a file, which is later renamed. The file of duplicate reports is then 
deleted. 

program Dupes; 
const 

Climat.File = 'climat.dat'; 
var 

Data.File: text; < file of weather obserrations > 

Dupe_File: text; { file of duplicate reports > 

Good.File: text; { file of good reports minus duplicates > 

procedure Discard_Dupes(var F, G. H: text); 

external; 

{ This procedure sorts F, a file of weather obserrations, 
saving good reports on file G and discarding duplicate 
reports on file H. > 

begin < Dupes > 

reset(Data.File, 'weax.dat'); 
rewrite(Dupe.File, 1 dupe.tap 1 ); 
rewrite(Good_File, 1 good.dat 1 ); 

Discard_Dupes(DataJFile, Good_File, Dupe_File); { Veed out the dupes } 
rename (Good.File, Climat.File) ; — renames GOOD.DAT to CLIMAT.DAT 

delete (Dupe.File) ; —-— deletes the file of duplicates 

end. { Dupes > 


Predefined Function ‘Time* 

The predefined function time takes no parameters and returns a real value corresponding to the 
current time of day. The value time is represented in hours after midnight, so that 9:30 a.m. is 9.50 
and 1:45 p.m. is 13.75. The resolution of time depends on the operating system, but all operating 
systems provide a resolution of at least one second. 

The value returned could be used in header information. (If you wanted the date as well as the 
time, you would use timestamp, described below.) Or you could call time at the beginning and end 
of a text-processing program and write a procedure that calculates the number of lines processed 
per minute, based on the difference in value returned. Or, because it generates a real number, time 
may be used to a seed n a pseudo-random number generator. The example below returns uses time 
to return the time of day. Chr(7) is the “bell” character. 

program VriteTime; 
var 

Hrs, Mins: integer; 

AmPm: packed array[1..2] of char; 


3-27 






Pascal-2 V2.1/RT-11 Language Specification 


begin -C IriteTime > 

Mins := Round (time * 60); 

Hrs := Mins div 60; 

Mins := Mins mod 60; 
if (Hrs < 12) then AmPm := 'AM* 
else if (Hrs = 12) and (Mins = 0) 
then AmPm := 'M ' :== ,pM '* 

write('At the tone the time will he. ). 
write(((Hrs+11) mod 12 + 1):2); 
writeO:'. Mins diw 10:1. Mins mod 10:1. 
writeln(Clir(7)); 
end. { IriteTime > 


AmPm: 3)) 


Running the program yields these results: 

At the tone the time will he: 11:37 AM <beep> 


Procedure ‘TimeStamp’ 

The timestamp procedure provides a way to 

Date and time are obtained simultaneously so that they are consist , 

T1 „..toup i. included in the P^nl-2 libr.ry, but the name i. not p,e-decla,ed b y the comp,. • 

You must include a definition similar to. 

procedure Timestamp(var day. month, year, 

hour, min, sec: integer ), 

external; 

The following program prints the date and time using timestamp, 
program DateTime(output); 

Day, Month. Year: Integer; < date data > 

Hour. Minute, Second: Integer; i time data > 


{ date > 
i time > 


var 


procedure Timestamp(var Day. Month. Year. 

F Hour. Min. Sec: Integer ). 

external; 


{ date > 
{ time > 


p T.£r< output tn. 

leading zeros if needed. The number must he 99 or less > 
write(output. N diT 10: 1. N mod 10: 1); 
end; { PrintTwo > 
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begin < DateTime > 

Timestamp(Day, Month, Year, Hour, Minute, Second); 
PrintTwo(Day); 
case Month of 

1: write(output, 1 -Jan- 1 ); 

2: write(output, 1 -Feb- 1 ); 

3: write(output, 1 -Mar- 1 ); 

4: write(output, 1 -Apr- 1 ); 

5: write (output, 1 -May- 1 ) ; 

6: write (output, ' - Jun- 1 ) ; 

7: write(output, 1 -Jul- 1 ); 

8: write (output, 1 -Aug- 1 ) ; 

9: write(output, 1 -Sep- 1 ); 

10: write(output, 1 -Oct- 1 ); 

11: write(output, 1 -Now- 1 ); 

12: write(output, '-Dec- 1 ); 
end; 

write(output. Year: 4, 1 '); 

PrintTwo(Hour); 
write(output, 1 : 1 ); 

PrintTwo(Minute); 
write(output, ': 1 ); 

Print Two (Second); 
write In (output); 
end. { DateTime > 

The results of the program are: 

16-Jun-1983 14:28:31 
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Error Handling 

This section describes the errors defined by the Pascal standard and Pascal-2's handling of them. 


Detected Errors 

Pascal-2 detects the following errors in all cases: 

1. Ln or sqrt has a negative argument. 

2. The integer value returned by trunc or round lies outside the range -maxint. .maxint. 

3. Integer or real division by zero. 

4. The result of a real operation eannot be expressed because of limitation, in the floating-point 
format. 

5. No label matches the value of the case index in a case statement. 

6. The characters being read from a text file do not represent a legal value for the type of 
being read. 

7. An attempt to call get, taad, or reaflln when the Ale ha. not been r.aat or when .of is tm. 
for that file. 

8. An attempt to call put, Tit., Tlt.ln, or page when the file has not been rewritten or when 
oof is false for that file. 

9. A call to put when the file variable is undefined. 

Pascal-2 detects the following errors under these conditions: 

detected when a negative mine i. aligned to an extended-range tumble. See Extended Range 
Arithmetic” for more details. 

2. An index expression for an array access is outside the range of the corresponding index type. 
Detected when the $indexcheck switch is enabled. (Default.) 

3 ' through an undefined 

value is not detected, although many cases will be detected at compile time. 

switch is enabled. (Default.) 

5 as? ss 

undefined pointer is sometimes detected. 

6. The result of the sqr function is out of range. Detected if the argument type » r.al; undetected 
if the argument type is integer. 

7. The result of chrCx) is not within the character set. Detected only if a xalue is assigned to a 
variable or is passed as a parameter. 

8. The result of aucc or pr.d lie. outside the range of the type. Detected only if the ralue then is 
assigned to a variable or is passed as a parameter. 

9. A .od with the right-hand side less than or equal to tero. Detected if the yalue is sero; otherwite 
not. 
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10. Reference to u undefined variable. Undetected in general. However, many simple cases are 
detected at compile time. 

11. A return from a function without a value being assigned to the function. Undetected in general. 
However, many simple cases are detected at compile time. 

12. An attempt to call put on a file that was opened with reset. Detected except for a file with 
the /seek file control switch specified when the file was opened. 


Undetected Errors 

Pascal-2 does not detect the following errors: 

1. A set value assigned to a set variable or value parameter contains members not in the range of 
the base type of the set variable. 

2. An access to a field in a variant record that is not selected by the current value of the tag-field. 

3. A dispose of a variable allocated on the heap while there is an active reference to that variable 
as a variable parameter or in a vlth statement. 

4. A change in the value of a file variable by a get or put while there is an active reference to 
that variable as a variable parameter or in a with statement. 

5. Accessing of a variable allocated with new (p, ej,.... e») as an entire variable, in an assignment 
or as a parameter. 

6. Calling of dispose(p) when the value of p* was created with nev(p, ej,..., c«), or calling of 
dispose (p, ci,.... c*) with a variable created with uev and a different set of tag values. 

7. The result of an integer operation is incorrect because of overflow. 

8. The value of a format expression to a write statement is less than 1. Undetected (used in a 
language extension). 
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Appendix A: Predefined Identifiers 


Constanta 

Falsa 

Maxlmt 

True 


functions 

ibs 

irctaa 

Bltslsa* 

Chr 


Types 

Booleaa 

Char 

Integer 

Beal 

Text 

Variables 

Iapmt 

Oatpat 


Cos 

Eof 

Cola 


Exp 

Ioerror* 

Iostatas* 

La 

Loopbole* 

044 

0r4 


Ref* 

Boaa4 

Sim 

Siam* 

Sqr 

Sqrfc 

Sace 

Tins* 

Traac 


Procedures 

Break* 

Close* 

Delete* 

Dispose 

Get 

lee 

Boioerror* 

Pack 

Page 

Pat 

Bead 

Bea41a 

Beaans* 

Beset 

Bewrite 

Seek* 

Unpack 

trite 

■ritela 


Appendix B: Reserved Words 

Aa4 

Array 

Begin 

Case 

Coast 

Din 

Do 

Donato 

Else 

Ea4 

External* 

Pile 

For 

Pomar4 


Paactioa 

Goto 

If 

la 

Label 

Mo4 

111 

loapascal* 

lot 

Of 

Or 

Origin* 

Othereise* 


Packed 

Proce4are 

Progran 

Record 

Repeat 

Set 

Tbea 

To 

TIP* 

Until 

Tar 

Vitb 

While 


• Items marked with the »«™k me ettetekm. ot .tmidmd Puc 


Updated January 
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Appendix C: Pascal-2 Syntax 


Pascal—2 Syntax Diagrams 

program 


T 


program heading 


7 


declarations 


i 


^ block -(7} j > - 


<7 


program heading —( programT}-) identifier ^ identifier 


T 


_ r Q 7 

declarations}^ begin ) —^ —[statement |— ^- ( end ) ->- 


block 


r 


declarations -^-j labels t 


consts 


types vars 


i 


vars 


y j procedure 
'—l function VJ 


labels . 


- (label} - 


<7 


^—I digit 1-7 


< 7 ^ 


consts-('const ) identifier - ( = ) - constant -(jy 


1 


♦yP es - (type ) 7- identifier type -(j^) > - 


vars. 


<7 


7 


identifier origin } - constant -j —^-(7}- tyP e 


constant 



structure component. 


constant 



<7 


structure component -^~C)Y 
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number 



-<E> 


type. 


type identifier}- 



—\ 


(J)—L- | identifier} -^—Q)- 


-[instant]— ( 77 ) —[constat 

—- type identifier | - 


^y( packed >j- 





field list 



variant part —f case 


identifier 


jfierV Qj~[ 


type identifier}-(of 



variant. 


procedure. 




■j procedure beading r v» 



block ) —j 
irectiveV 


-r-Qy*~ 


directive 


<— f procedure }— identifier bloc k 


function. 


function heading]-(T)~^ U ? lo 5* 


blocK | —7- 
directiveV 


KD^ 


<- ( function V f identifier> <TH^!g^J 
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function heading 



-o 


— ( functiony - l identifier] --^r-(X) ^ formal parameter p -Q 



type identifier 


directive 


forward ) — 
^ extemaT) -^ 
X nonpascal y 



conformant array schema _ 

packed array ) —(J)— index type spec —(J)— (of) — type 

K7>— 


array 


XD-HI 


index type spec 



of 


X 


type 


conformant array schema 


J 


index type spec-1 bound identifier K^DH bound identifie7}-{T)--|~type 
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factor 



unsigned constant 
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statement. 


X 


dicntl-- ^ C \ 


digit unlabeled statement 


unlabeled statement 


^ begin — | statement (ancP) 


STOQ-lBoolean expression |-(jthen )~[ statement |— 


variable 


expression 


procedure identifier] -^^ expression 


i 


o 

<E> 


<D 


/ 


<I> 


1 


T 


X )case) - expression -(l)f) 


<i> 


O 


constant 

-KD- 

statement 

-( otherwise )— 

statement 




end )—' 


while ) - j Boolean expression - ( do } - j statement 

—<D— 


^ ( repeat ) -^— statement —^- (until) - Boolean expression 


downto 


for) ~ [variable expression k - (to) - J expression} -{ jdb) )- | statement 

-O— 




irit.h \ C r 


with ^— j record variable —^- ( do ) - statement 
K goto ) -^— | digit f —^-- 
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Extended Backus-Naur Form 



lNlKiaiiH YYirbil ^ YYiiau vou **-—-- ~ 

Definitions?", Communications of the ACM , November 1977, vol. 20, number 1 ). 

A “terminal symbol” is a symbol that actually appears in the language itself. Examples of terminal 


symbols in Pascal are: 


begin + >= 

Terminal symbols are written in quotes, e.g.: terminal . 


Some terminal symbols are not eaailj expremed in tbi. »aj, and the* may be r.pre..nted by 


comments contained in angle brackets < >. For example, 
<any printable character^ 



appear 

symbol 

written 


A “nonterminal symbol" is used in 
in the text of the language. That is, 
will stand for some sequence of term 
without quotes. For example: 


identifier, interface-part 


A “production” is a rule specifying which terminal and nonterminal symbols make up another 


nonterminal symbol. A production is written. 
left-hand-side = right-hand-side . 


i i.i _i_ti l_j o/Mvia of terminal and 



the right-hand-side. A production is terminated with a period. 
Within a right-hand-side, the following operators may occur: 


(blank) indicates that the two symbols are concatenated. For example: 


Ihs = “a” “b” “c” . 

indicates that Ihs consists of the string abc. 


| (vertical bar) indicates that the two symbols are alternatives. Concatenation is performed 


before alternation. For example: 


Ihs = “ab” | “cd” . 

indicates that Ihs consists of one of the strings ab, cd. 

[ ] (brackets) indicate that the enclosed symbols are optional. For example: 

Ihs = “a” [“be”] “d” . 

indicates that Ihs consists of one of the strings abed, ad. 

{} (braces) indicate that the enclosed symbols are repeated sero or more times. For example: 

Ihs = “a” {“b”}“c” . 
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indicates that Ihs consists of any of ac, abc, abbc, abbbe. 

( ) (parentheses) are used for grouping as they are in mathematics. 

We can now use this notation to describe itself as an example. The productions for fetter, digit and 
character are not given here but are obvious. 

syntax = {production }. 

production a nonterminal-symbol “=*" expression . 
expression a term {“|" term }. 
term a /actor { factor }. 

/actor a nonterminal-symbol | terminal-symbol | “(” expression “)" 

| “(” expression “)" | “<” expression “}” . 

terminal-symbol a character {character }“•’ | <any comment in angle brackets> . 
nonterminal-symbol a fetter {fetter | digit | }. 


Pascal-2 Lexical Description 

This set of productions defines the lexical representation of Pascal-2. 

Productions that differ from the standard are marked with an asterisk (*). 

The case of any alphabetic character is insignificant except in a character-string. Lower-case is used 
in this description. 


1 .* 


fetter - “a" | “b” | “c" | “d” | | “f” | “g" | f |“i” 

| “J” | “k” | “1” | V | V | “o’ | -p- | “q” | “r” 

| “a” | “t” | “a” |V|V|¥|y| | “I’ . 


2. digit = “0" | “I” | “2” | “3- | “4- | “6” | “6” | “7- | “S’ | “9” . 

3 . * octal-digit = “ 0 " | “ 1 " | “ 2 ” | “ 3 " | “ 4 " | “ 6 " | “ 3 " | “ 7 ” . 


4. * hexadecimal-digit — digit | “a" | “b” | “c" | “d” | “e” | “f ” . 

5. special-symbol a “♦” | | “•* | “/’ | “a" | “<” | “>” | “(” | “j” | “(.’ | “.)” 

| | | | | — | “T | T I T I “<>” I I 

j | | word-symbol . 

6. * word-symbol a “and” | “array" | “begin" | “case” | “const” | “dir” | “do” 

| “dostto’ | “else” | “sad” | “file" | “for” | “fanctioa” | “goto” | “If” 

| “la” | “label” | “nod” | “all” | “not” | “of” | “or” | “origin” | “otherwise” 
( “packed” | “procedare” | “progran” | “record” | “repeat” | “set” | “then” 
j “to” | “type” | “until” | “var” | “while” | “with” . 

7. * identifier a fetter {letter \ digit | }. 

8. bound-identifier a identiSer . 


9* directive a “forward” | “external” | “nonpascal” . 

10. digit-sequence a digit {digit }. 

11. * unsigned-integer a [ digit-sequence “•” | hexadecimal-digit-sequence . 


12. unsigned-real a ( unsigned-integer “.* digit-sequence [ “E” scale-factor J ) 
fi (unsigned-integer “E” scale-factor). 
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13. * nondecimaJ-integer ■ digit-sequence 

( hexadecimal-digit { hexadecimal-digit }| octal-number ). 

14. * octal-number «■ octal-digit { octal-digit }“b" . 

15. * unsigned-number — unsigned-integer \ unsigned-real \ octal-number . 

16. scale-factor — signed-integer . 

17. sign - | • 

18. signed-integer — ( sign | unsigned-integer; 

19. signed-real — ( sign j unsigned-real; 

20. * signed-number — signed-integer \ signed-real | { sign ] octal-number . 

21. label — unsigned-integer; 

22. character-string — “•* string-element {string-element }“•" . 

23. string-element — | <apy printable ASCII character> . 

24. comment *■(“{" | “(•" ) 

<*Hjr sequence of characters and ends of lines not containing “>* or “•)"> 

( “>" I “•)" ) • 

25* lexical-directive - “finclude* Ble-name-string “•* | Ip***’ V . 

Pascal-3 EBNP Syntax 

This set of productions defines the syntax for the language accepted by the Pascal-2 compiler, 
including all extensions. 

This section is to be interpreted in conjunction with the lexical description of the language. 

Productions are based on those in the ISO standard. Where the language accepted by the Pascal-2 
compiler differs from this standard, the production is marked with an asterisk (“•"). 

1. * program = ( program-heading J { label-declaration-part 

| constant-deBnition-part | type-deBnition-part 
| variable-declaration-part | routine-declaration }( body “." J . 

2. program-heading ■» “prograa" identifier [ “(" program-parameters 

3. program-parameters * identifier identifier }. 

4. block *■ declarations body . 

5. * declarations ■ | labeldeclaration-part | ( constant-deBnition-part j 

( type-deBnition-part j { variable-declaration-part ] {routine-declaration }. 

6. label-declaration-part « “label" label label }“;* . 

7. constant-deBnition-part *■ “const" constant-definition constant-definition . 

8. constant-definition a identifier “«* constant. 

9. * constant =» ( ( sign | ( unsigned-number | identifier )) 

| character-string | structured-constant . 

10. * structured-constant ■ structured-type-identiBer constant-component-list . 

11. * constant-component-list «■ “(" constant-component constant-component }“)” . 

12. * constant-component ■ constant | constant-component-list. 


Updated January 1884 
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13. type-definition-part = “type* type-definition {“;” type-definition } u ; n . 

14. type-definition = identifier “=” type . 

15. type = identifier | enumerated-type | subrange-type \ set-type 

| array-type | record-type | file-type | ( | “0” identifier ) . 

16. enumerated-type = “(” identiSer {“,” identifier }“)” . 

17. subrange-type = constant “..” constant . 

18. set-type = [ “packed” ] “set” “of” type . 

19. array-type = [ “packed” ] “array” “[” type {“,” type }“]” “of” type . 

20. record-type = [ “packed” ] “record” field-list [ ] “end” . 

21. field-list = ( fixed-part [ “;” variant-part ] ) | variant-part . 

22. fixed-part = record-section {“;” record-section }. 

23. record-section = identifier identifier type . 

24. variant-part = “case” [ identifier “:” ] identifier “of” variant variant }. 

25. variant = constant constant }“:” “(” [ field-list ][“;”] “)” . 

26. file-type = [ “packed” ] “file” “of” type . 

27. variable-declaration-part = “var” variable-declaration { variable-declaration }. 

28. variable-declaration = var-specification {“,” var-specification type . 

29. var-specification = identifier [ “origin” constant ] . 

30. routine-declaration = ( procedure-declaration | function-declaration ) . 

31. procedure-declaration = ( procedure-beading WocJt) 

| ( procedure-beading “;” directive ) [ ( procedure-ident “;” block) . 

32. procedure-beading = “procedure” identifier [ parameter-list ] . 

33. procedure-ident = “procedure” identifier . 

34. function-declaration = ( function-beading “;” block ) 

| ( function-beading “;” directive ) | ( function-ident block) . 

35. function-beading = “function” identifier [ parameter-list ] “:” identiSer . 

36. function-ident = “function” identifier . 

37. parameter-list = “(” parameter-section {“;” parameter-section }“)” . 

38. parameter-section = ( [ “var” ] identifier identifier (identifier 

| conformant-array-scbema )) | procedure-beading | function-beading . 

39. conformant-array-scbema = p acked-con form ant-array-scbema 

| unpacked-conformant-array-scbema . 

40. packed-conformant-array-schema = “packed” “array” 

“[” index-type-specification “]” “of” type . 

41. unpacked-conformant-arrayschema = “array” “[” index-type-specification 

{“;” index-type-specification }“]” “of” ( type | conformant-array-scbema ) . 

42. index-type-specification = bound-identifier bound-identifier “:” type . 

43. body = compound-statement . 
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44. statement = [ label “:” ] 

[ assignment | procedure-call | compound-statement | if-statement 
| case-statement | while-statement | repeat-statement 
| for-statement | w ith-statement | goto-statement ] . 

45. assignment = variable “: =” expression . 

46. procedure-call = identifier [ arg-list | write-arg-Iist ] . 

47. arg-list = “(” expression {“,” expression }“)” . 

48. write-arg-Iist = “(” write-arg {V write-arg } “)” . 

49. write-arg = expression [ expression [ “:” expression ] ] . 

50. compound-statement = “begin* statement { ; statement } end . 

51. if-statement = “if* expression “then* statement [ “else” statement ] . 

52. * case-statement = “case” expression “oi” [ case-element {“;* case-element }][“;”] 

[ “otherwise” statement [*;”]] “end” . 

53. case-element = constant constant statement . 

54. while-statement = “while” expression “do” statement. 

55. repeat-statement = “repeat” statement {“;” statement }“until” expression . 

58. for-statement = “for” identifier “:=” expression ( “to” | “downto” ) expression 
“do* statement . 

57. with-statement = “with” expression {“,” expression }“do” statement . 

58. goto-statement = “goto” label . 

59. expression == simple-expression [ relational-operator simple-expression ] . 

60. relational-operator = “<” | a >” | “<=” | “>==” | = | <> | in . 

61. simple-expression = [ sign ] term { adding-operator term }. 

62. adding-operator = “+” | a ~” | “or” . 

63. term = factor {multiplying-operator factor }. 

64. multiplying-operator = | V” | a div” | “mod | and . 

65. factor = unsigned-constant | variable | function-call | “not” factor 

| “(” expression “)” | bound-identi&er | ( a [ n | “(•" ) 

[ member-designator {“,” member-designator }] ( “]” | U -Y ) • 

66. unsigned-constant = unsigned-number | string | identiSer | “nil” . 

67. function-call — identiSer [ a rg-list ] . 

68. variable = identiSer | variable ( “[” | “(.” ) expression { , expression } 

( «]» | “.)” ) | variable ( “"” | “0” ) | variable “.” identiSer . 

69. member-designator = expression [ “..” expression ] . 
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Debugging tools help uncover “run-time" errors—errors ia a program’s execution—that cannot be 
caught during compilation. For example, a procedure may generate an incorrect number of loops 
or make a legal but unintended change in the value of a variable. The Pascal-2 Debugger lets you 
control a program’s execution interactively; you may suspend execution at particular statements to 
examine or modify the values of variables, or you may execute statements one at a time to trace the 
actions leading to an incorrect result. 

When called, the Pascal-2 Debugger keeps track of all constants, variables, local procedures and 
functions and all standard and user-defined data types. The Debugger can show what's happening 
to data and allow you to change the data as the program executes. You can display the original source 
text of your program for immediate identification of context, and yon can access and debug external 
procedures and functions called by the main program. (See “Debugging External Modules” at the 
end of this guide for details.) The Debugger also traps errors by halting execution of a program at 
the point of breakdown and identifying the last statement executed. Taken together, these features 
allow you to trouble-shoot a program until you have detected and corrected any errors. 

This guide serves as an introduction to the Pascal-2 debugging process and as a comprehensive 
resource for operation of the Pascal-2 Debugger. The guide provides: 

s An overview of the Pascal-2 debugging environment. 

s Detailed descriptions of the Debugger commands. 

s A tutorial that demonstrates the context in which Pascal-2 Debugger commands are most 
frequently used. 

• An explanation of how external modules are debugged. 

• A one-page summary of Debugger commands. 

A word of warning before beginning: specifying the debugging option causes the compiler to include 
a call to the Debugger before each procedure and statement, which substantially increases the size of 
your program. The object module created by the compiler contains extra code to locate statements 
and procedures in your program. Moreover, introducing the Debugger turns off optimizations that 
would interfere with debugging. The compiler normally folds similar statements into one section of 
code and optimizes the usage of some variables by keeping their values in registers on the stack 
temporarily. These optimizations would keep the Debugger from setting breakpoints in statements 
and from changing the values of variables while your program was running—both of which are 
important debugging facilities. A little bit of memory is saved during use of the Debugger by disabling 
the procedure walkback—this happens automatically when the Debugger is implemented—but in 
general, the overhead involved in using the Pascal-2 Debugger is about one word per Pascal statement 
and about six words per procedure. Code returns to its normal size once you correct any problems 
and recompile your program without a call to the Debugger. (See “Overlays” in this guide regarding 
what to do if the program grows too large.) 


4-1 


Updated January 1086 






Pascal-* Vl.l/RT-11 Debugger Guide 


Including the Pascal-2 Debugger in Your Program 

The debeg compilation switch invoke, the Pascal-2 Debugger. (See the User Guide for detail, on 
compilation switches.) Using the debug switch in your compilation generate, 

a formatted listing file, with an .LST extension, ui the same directory a. the output file. The Debugger 
reads this listing file to display the source line, when statement, are identified. The Debugger can 
use only the listing file produced by the debug switch. 

The debug switch also cause, the compUer to create symbol table and statement map file, in the 
He directory a. the output file. The symbol table file (extension SYM) describe. the constant., 
tvoe. variable, and the memory layout of variable.. The symbol table file also contain, information 
about each procedure and function local to the compilation unit. The statement map file («**"“* 
SMP) contains a map of the location of the statements and their position in the listing. Both file, 
are in binary form and are not readily examined by user*. 

R PASCAL 
eRQTAT/DEBW. 

IiTII ROTiT ST. PASCAL 
Identifying Plietl Statements 

Remember, the debug switch automatically generate, a listing file. As the example ROTAT.LST 
shows, a listing file has two columns of numbers. The leftmost column lists the line numbers in the 
source file. The second column contains the number of each statement in the program, beginning 
with T for each procedure or function. These numbers identify points where you may set breakpoints 
to interrupt program execution. In ROTAT.LST, several line, accessible totheDebuggerhave been 
labeled by procedure name and statement number. As shown, statements in the main body °T the 
program are considered to be in the procedure Mill. All Pascal programs begin executing at MAIi. 1. 

You should have a printout of the listing file as reference when you begin a debugging semion, or 
you may use the L command to list parts of the program while you are debugging. 


£ I 

V 
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Ineluding the Pascal-2 Debugger In Your Program 


Example: 


Pascal-2 Bill SJ T2.1D 9-F«b-84 7:00 AM Site #1-1 Page 1-1 

Oregoa Software, 0915 ST Macadan Awe., Portland, Oregon 97219, (503) 245-2202 
ROTAT/DEBUG 
Line Stnt 


1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 
26 
28 

27 

28 

29 

30 

31 


prograa Rotat; { rotate an array of nnabers > 
const Arraylen = 7; 

type Index * 1..Arraylen; Eleasnt = 0..10; 

■ambers = array [Index] of Element; 

rar I: Index; ■: lumbers; Left, Right: Index; 

procedure Rotate(First, Last: Index; 

rar A: lumbers); 

Tar I: Index; 

1 begin 

2 for I := First to Last do 

3 A [I] :* A [I ♦ 1]; -BOIATE, 3 

4 A [Last] : = A [First]; -ROTATE, 4 

5 write (’Rotated ’, first: 1, * thru ’, last: 1, ’=’); 

end; 

1 begin { main program > -MAII, 1 

2 for I :* 1 to Arraylen do 

3 begin I[I] := I; write(I: 2); end; 

5 writeln; write(’Left,Right? ’); 

7 readIn(Left, Right); 

8 I := 4; 

9 Rotate(Left, Right, I); 

10 for I :* 1 to Arraylen do 

11 wrlte(I[I]: 2); 

12 writeln 
end. 


ass lo lines with errors detected see 


ROTAT .PAS is worth studying for a moment because it appears frequently throughout the remainder 
of this guide. The program prints an array of seven integers, then prompts you, asking for a starting 
and ending point in the array. Once the two input numbers have been entered, the program is 
supposed to rotate that section of integers to the left, with the left digit replacing the right. In its 
current form, the program compiles without problem, but as is shown in several of the following 
sections, its execution encounters numerous run-time errors. 
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Controlling the Debugger 

Debugger takes control of the program, enters the command mode, and prompts with a right brace 
*}’ symbol. (This may print on upper-case-only terminals as the right bracket *]’ character.) 

B2UB2IAI 

Pascal Debugger T3.00 — 29-Iov-1983 
Debugging prograa ROTAT 
> 

You control the Debugger through single-character commands that generally take one of two forms, 
depending on whether or not the command accepts parameters: 

} single-character command 

> single-character command ( parameters) ) 

Debugger commands and their parameters may be typed in either upper or lower case. 

Command Syntax 

In general, Debugger commands are used for controlling breakpoints, program execution, program 
tracking, data, and for displaying information about the data being maintained by the Debugger. 
Debugger commands can be stored in series and executed at designated locations within a program. 
Such locations are known as breakpoints and are specified by the break command. At any breakpoint, 
you may enter as many stored commands as fit on a single line. Any Debugger command may appear 
in a stored command and certain utility commands, described later, allow macros to be defined that 
let you store combined commands. 

As an example of the general use of Debugger commands and the syntax for writing stored commands, 
look at the following command line. The line begins with the single-character command B followed by 
the parameter ROTATE,3. These direct the Debugger to set a breakpoint at statement 3 in procedure 
ROTATE. Next, a stored command is used to instruct the Debugger to write (1) the values of the 
variables I and All). Stored commands are specified by placing them within angle brackets (<...>) 
after a break command and separating them by semicolons. 

> B(ROTATE.3) <W(I): W(AtlD> 

The Debugger accepts any of the single-character commands defined in the following sections. 
Numeric parameters in these sections are indicated by ‘n\ as in the command S(n). A summary of 
the Debugger commands is given in Appendix A at the end of this guide, and the T (question mark) 
command prints a similar list on your terminal screen. 
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Controlling the Debugger 


Exiting and Stopping the Debugger 

To exit from the Debugger at the prompt, give the command Q (quit), or type a Control-Z (~Z), or 
type Control-C (“C) twice in a row. A single Control-C (*C) typed during program execution stops 
the Debugger, thus permitting you to break into “infinite loops” in your program. 

Selective Debugging 

For certain large programs, you may wish to selectively debug portions of a program in order to speed 
up the debugging process or to reduce the amount of memory overhead created by the Debugger. 
You can edit your program to turn off generation of debugging information around procedures that 
have already been tested and debugged by using the embedded directives Inodebng and Idebng. To 
turn off debugging, place the directive Inodebng before the procedure definition and the directive 
Idebng after the procedure. Ilodebng and Idebng are effective only when the /debug switch is first 
specified in the compilation command line. Otherwise they are ignored by the compiler. (See the 
User Guide for further details on embedded directives.) 



I 

V 

i 

| 

I 
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Breakpoint Commands 

Breakpoint commands allow you to set or remove breakpoints when your program reaches a certain 
point in execution or when a specified variable in your program changes value. Breakpoints allow 
you to interrupt the program in order to execute other Debugger commands. 


B y B(): Control Breakpoints 

A program control breakpoint is identified by two items: a block name (procedure, function, or MAII), 
and a statement number within that block. For example, ROTATE,3 identifies the third statement in 
the procedure ROTATE. Statements are sequentially numbered within each block. Statement numbers 
are listed in the second column of the program listing produced by the debug switch. 

The Bfb/oclr.stmtnujn) command sets a control breakpoint within the block named block at the 
statement numbered stmtnum. When the breakpoint is reached, your program is interrupted before 
execution of the named statement, the breakpoint is identified, and the Pascal source line is displayed. 
The Debugger then accepts commands. 

These may be interactive commands (from your terminal) or stored commands executed automati¬ 
cally. Any Debugger command may be stored for execution at a breakpoint. Stored commands 
are executed before interactive commands. If the stored commands direct the Debugger to resume 
execution, the program continues without waiting for an interactive command. 

You may interrupt the program at any time with a Control-C (*C). This command stops the program 
and identifies the point of interruption as if you had set a control breakpoint. 

NOTE 

If you type a Control-C (*C) while the program is awaiting input for a real 
or an integer at a read or readln statement, the Control-C (~C) does not 
take effect until after you have completed the input request. 


A run-time error or program termination also causes a control breakpoint after the error message 
or termination status is displayed. You may set any number of control breakpoints. (The program 
executes more slowly if you define many.) 

To set breakpoints in external functions and procedures, see “Debugging External Modules” later in 
this guide. 

You may remove a breakpoint in two ways. The B command with no parameters deletes the 
breakpoint that most recently stopped the program. Otherwise, the K command described next may 
be used. (For uses of the B command, see the example listed after the C command.) 

K 9 K(): Killing of Breakpoints 

The JL^block,stmtnum) command deletes the breakpoint specified by its parameter; the K command 
with no parameters removes all breakpoints. (See the example alter the C command.) To remove 
breakpoints in external functions and procedures, see “Debugging External Modules” later in this 
guide. 
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V, V()i Data Breakpoints (Variables) 

The data breakpoint facility (also called the “watched variable” command) causes an immediate 
breakpoint when the value of a specified variable is changed. The V (variable) command sets a data 
breakpoint, with variable indicating the variable to be monitored. When the value of the variable 
is changed, the Debugger prints both the old and new values and interrupts program execution 
for commands. Like control breakpoints, data breakpoints may have stored commands that are 
automatically executed when the breakpoint is triggered. A list of the stored commands, separated 
by semicolons, is enclosed in angle brackets after the watched variable command: V(variab/e)< ... >. 

The V command monitors a variable of any type, but only the first 32 bytes of data is watched. You 
may watch any number of variables. (The program executes slowly if you set many.) For variables 
defined locally to a procedure, the watch command can either be set from within the procedure or 
through use of the E command defined later in this guide. 

) B (ROTATE. 1)<T(A[01)> -variable watch set within ROTATE 

) 5. ---begin execution 

Left,Right? 2_J& -input to ROTAT 

Breakpoint at ROTATE,1 begin 

} £ -continue execution 

The value of 'A[6]* vas changed by the statement: 

ROTATE,3 A[I] := A[I ♦ lj; 

Old value: 0 
lev value: 7 

Breakpoint at ROTATE.4 A[Last] := A[First]; 

) 


If a local variable is being monitored and the associated block is completed, the Debugger removes 
the breakpoint and displays a message that the variable no longer exists. 


Breakpoint at ROTATE, 1 begin -previously set breakpoint 

) L -lists statements of procedure ROTATE 


14 1 

15 2 

10 3 

17 4 

10 5 

19 

} T(Af2]) 

} £ 


begin 

for I := First to Last do 
A[I] := A[I ♦ 1]; 

A [Last] := A [First]; 

vriteCRotated ’, first: 1, * thru *, last: 1, ’=•); 
end; 

-- variable watched within ROTATE 


The value of "A[2]** vas changed by the stateaent: 
ROTATE,3 A[I] := A[I ♦ 1]; 

Old value: 2 
lev value: 3 

Breakpoint at ROTATE,3 A[I] := A[I * 1]; 

> £ 


latch terminated for **A[2]*’ Value did not change. 

Rotated 2 thru 0 s 1345037 - indicates a run-time error 

> 


This example gives us our first indication of a problem in the program ROTAT .PAS. The correct 
rotation for the starting and ending points (2.0) should read 1345027 not 134503 7. 
Correction of the problem is explained in the section “Stepping Through a Debugging Session” later 
in this guide. 

The V command without parameters removes all data breakpoints. It is not possible to remove 
individual data breakpoints. 
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Execution Control Commands 

Execution control commands provide the means to monitor and control the flow of the program. 
The commands initiate, interrupt, or continue execution. 


Gx Go 

The G (Go) command begins executing the program at MAII.l and may be used at any point in the 
program to restart it. 

See the example after the C command. 


C 9 C()x Continue Execution 

The C (Continue) command resumes program execution from the current breakpoint. 

If you set a breakpoint inside a loop, you may use the C(n) command to let the statement at 
the breakpoint execute n times. For instance, you may set a breakpoint at COURT,10 inside a loop 
structure. When the Debugger stops at that breakpoint, you may give the command C(6) to let 
the loop iterate six times before the program stops again at COURT, 10. Each breakpoint has its own 
counter, which is independent of the counters for other breakpoints. 

The C command functions like the G command to begin executing the program if you are at the 
start of the program. 

If you use the C command after the program has terminated, you receive an error message telling 
you to use the G command to restart the program. 


Examples of the B f K, D, G and C Commands 
• KOLMIAI 

Pascal Debugger V3.00 — 29-Vov-1983 
Debugging prograa ROTAT 

} LCsilft. 8 ,3} - List 8th statement of MAII, 2 lines 

20 8 I := 4; 

27 0 Rotate(Left, Right, I); 

> B(nain.9)<f(*!=*.i);C> 

} B(Rotate.3)<I(*In rot ate. I=M)> 

> fi 

1 2 3 4 5 8 7 

Left,Right? -input to ROTAT 

Breakpoint at RAH.9 Rotate(Left, Right. I); 

I* 4 

Breakpoint at ROTATE,3 A[I] := A[I ♦ 1]; 

In rotate. Is 2 

) & —-— display breakpoints 

Breakpoints 

ROTATE,3 A[I] := A[I ♦ 1]; 

<I(’In rotate, I=’,I)> 

MAII.9 Rotate(Left, Right, I); 

<ICI=M);C> 
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Execution Control Commands 


} KDLgm ; f (I} 

2 

Breakpoint at ROTATE,3 A[I] := A[I ♦ 1]; 
In rotate, 1= 4 

4 

> K(Rotate.3) - 

> £ - 

Rotated 2 thru 8= 1345637 - 

} ft - 


Breakpoints 

MAI1,9 Rotate(Left, Right, I); 
<f(’!=•,I);C> 


) & - 

> 1\ 

-kill all breakpoints 

/ 1 i 

> a - 

(no breakpoints to display) 
-quit the Debugger 


kill specified breakpoint 

-continue execution 

indicates run-time error 
-display breakpoints 


S, S(): Step to Next Statement 

The S (Step) command executes the next statement of the program. The S(n) command executes n 
statements without interruption. If a statement being “stepped” calls another procedure or function, 
that new procedure or function also is executed one step at a time. 

See the example after the P command. 


P 9 P(): Proceed to Next Statement 

The P (Proceed) command executes the next statement at the current level of the program. P 
differs from S in that P does not single-step through functions and procedures called by the current 
statement. P treats an entire nested call as a single statement; thus procedure calls and function 
invocations are completed before program control returns to the Debugger, allowing you to bypass 
the detailed execution of routines (e.g., ones already debugged). If the current procedure ends, P 
begins single-stepping the procedure that called the current procedure. 

The P(n) command is equivalent to repeating the P command n times. 

As with the C command, you may not go past the end of the program with an S or a P command. 
If you do so, you receive an error message telling you to use G to restart the program. 
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Examples of the S and P Commands 

• WU PQI A1 

Pascal Debagger V3.00 — 29-low-1903 
Debagging progran ROTAT 


> &(aal ! L. 9 l 

} a 


1 2 3 4 5 0 7 

Left.Right? l_i - 

Breakpoint at MAII.9 Rotate(Left. Right, I); 


> £ 

Breakpoint at ROTATE,1 

> S 

Breakpoint at ROTATE,2 

} £ 

Breakpoint at ROTATE,3 

) S 

Breakpoint at ROTATE,3 

> £lil 

Breakpoint at ROTATE,4 

> C 


begin; 

for I := First to Last do 
A Cl] := A [I ♦ 1]; 

All] := All ♦ 1]; 

A [Last] : = A[First]; 


input to ROTAT 


Rotated 1 thru 5 s 2345207 -further indication of run-time error 


> a 

1 2 3 4 5 0 7 

Left,Right? 1 5 -input to ROTAT 

Breakpoint at MAII,9 Rotate(Left, Right, I); 

) E 

Breakpoint at MAII,10 for I := 1 to Arraylen do 

> E 

Breakpoint at MAII,11 write(I[I]:2); 

} E 

Breakpoint at MAII.ll write(I[I]:2); 

> E 

Breakpoint at MAII.ll write(I[I]:2); 

> Eifii 

Rotated 1 thru 5= 2345207 -same indication of a problem 

} 
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Tracking Commands 

Two commands help you track program execution. The H command lists the statements that have 
brought you to your present position. The T command traces program execution through each 
statement. 

H, HOs History of Program Execution 

The Debugger maintains a list of the last 50 statements executed while your program was running. 
With the H command you may review this execution history. For instance, if the program failed 
because of an error during execution (such as division by zero), the H command shows the steps 
leading to the statement causing the error. The H command with no parameters prints a list of the 
last 10 statements executed. H(n) prints the last n statements up to 50. 

The H command has other important functions as well. See Execution Stack Commands” for details 
and for examples of the command. 

T()t Execution Trace 

The T command accepts a Boolean parameter, either enabling or disabling the tracing of program 
execution. When tracing is enabled with the I (TRUE) command, each statement is identified by its 
block name and statement number and is displayed before being executed. 

A Control-C (*C) interrupts the trace and returns the Debugger to command mode. You may 
then turn off tracing with the T (FALSE) command and continue running your program with the 
C command. 


Example of the T Command 

.BIDLMIAI 

Pascal Debugger ¥3.00 — 29-Vot-1983 
Debugging program ROTAT 
> 

27 0 Rotate(Left, Right. I); 

28 10 for I := 1 to Arraylen do 

29 11 write(I[I]:2); 

) Mima. - -set breakpoint 

> £ 

1 2 3 4 6 6 7 

Left,Right? 1_1 -input to ROTAT 

Breakpoint at Mill,9 Rotate(Left, Right. I); 

> T(TBTC) 

> £ 
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ROTATE. 1 begin -—-tracing output begins 

ROTATE.2 for I := First to Last do 
ROTATE,3 A[I] := A[I ♦ 11; 

ROTATE,3 A[I] := A[I ♦ 1]; 

ROTATE. 3 A [I] := A [I ♦ 1]; 

ROTATE.4 A[Last] : = A[First]; 

ROTATE,5 srite(‘Rotated '.first: 1.* thru ‘.last: 1.‘=‘); 

MAII.IO for I :* 1 to Arraylen do 
MAII.ll write(I[I]:2); 

MAH. 11 Trite (I [I]: 2); 

MAII.ll Trite (I[I]:2); 

MAII.ll Trite (I[I]: 2); 

MAII.ll Trite (I[I]:2); 

MAII.ll Trite (I[I]: 2); 

MAII.ll Trite (I[I]: 2); 

MAII,12 Triteln 

Rotated 1 thru 3 s 2324567 -our run-time error is still evident 

} T (FALSE) -tracing off 

> K 

> 1 

1 2 3 4 5 6 7 

Left,Right? -input to ROTAT 

Rotated 1 thru 3* 2324567 

> 
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Data Commands 

Debugger data commands allow you to display the current values of variables and to assign new 
values to them. The data commands provide full access to user identifiers and type definitions. The 
data commands conform to Pascal type compatibility rules. 


1 ()t Write Variable Value 

You use the V command to write the value of a variable (including a pointer), of a constant, or of a 
memory location. The format for the V command is: 

> I(namei.pame2.name3. ...) 

where name is the name of the variable you want written. As shown, you may write the value of 
more than one variable by separating variable names with commas. 

The type of variable determines the format of the output. For example, integers are displayed as 
signed decimal numbers. Set variables a*e displayed in Pascal set notation. Scalar variables are 
displayed as the names of the enumerated types they represent. 

You may use the Pascal colon notation V to alter the way variables are written. For example, to 
print the integer variable I as a hexadecimal number, you use: 

> IjCIlt.11 

Also see the example after Variable Assignment. 

Real numbers may be formatted according to the same rules used by the compiler. 

A numeric constant is used as an address if you wish to write the integer value contained in a memory 
location. A ‘B' placed after the number, as in V(27740B), specifies an octal memory location. Memory 
locations are displayed as signed integers. 

✓ 

The Debugger may write any complex Pascal data structure, including records and arrays, except 
files. 

The Debugger displays an array in an orderly fashion that reflects the array's structure. For each 
change in the least significant (rightmost) index of the array, the Debugger writes a space between 
elements. For each change in the next least significant (second-from-rightmost) index, the Debugger 
starts a new line. And for changes in the nth index, where n is the number of “places from the 
right” of the least significant index and n is greater than 2, the Debugger writes n — 2 blank lines 
and indents the first row of the display n — 2 spaces. 
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Example: 

Pascal-2 BT11 SJ T2.1D 9-Feb-84 7:06 AM Site #1-1 Page 1-1 

Oregoa Softvare, 6915 SV Macadam Are., Portland, Oregoa 97219, (503) 245-2202 
MULTI/DEBUG 

Line Stat 

1 program Haiti; < multidimensional rariables > 

2 

3 rar A: array [1..3, 1..3, 1..3] of integer; 

4 I, J, I: integer; 

6 

6 1 begin 

7 2 for I := 1 to 3 do 

8 3 for J :* 1 to 3 do 

9 4 for K :» 1 to 3 do 

10 6 Atl.J.K] := (I • 10 ♦ J) • 10 ♦ K; 

11 end. 

*** lo lines vith errors detected ••• 


■ BUI MULTI 

Pascal Debugger 73.00 — 29-Mot-1983 
Debugging program MULTI 

> a 

> mi 

111 112 113 
121 122 123 
131 132 133 

211 212 213 
221 222 223 
231 232 233 

311 312 313 
321 322 323 
331 332 333 

When you write records, the Debugger lists each field name followed by the value of that field. The 
format of each field is determined by the data type of the field. Complex records, such as those 
containing arrays of records, can get messy; you may want to have the listing on hand to show the 
definition of the record being printed. 


Variable Assignment 

The Debugger command to modify the value of a program variable is identical in form to a Pascal 
assignment statement. The left-hand side of the *:=’ assignment operator indicates the variable to 
be modified. This variable may include array indices, record field selectors, and pointer accesses. 
The right-hand side specifies the value to be assigned. This may be a simple constant or literal 
value, or another program variable. Standard notation is used for all values, including sets. General 
expressions (operators and functions) are not permitted. 
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Debugger variable assignments must conform to the Pascal assignment compatibility rules. All 
variables accessed in an assignment command must be available in the current stack context. The 
E (a) command may be used to temporarily change context, if necessary. 


Examples of the W Command and Variable Assignment 

Pascal-2 RT11 SJ T2.1D 9-Feb-84 7:00 AM Site *1-1 Page 1-1 

Oregoa Software, 0015 SV Macadaa Awe.. Portland, Oregon 07210, (503) 245-2202 
COLOR/DEBUG 


Line 

Stnt 


1 


prograa Color; 

2 

3 


type 

4 


Color = (Red, Orange, Yellow, Blue, Green); 

5 

0 


var 

7 


c: Color; I: Integer; 

0 


Colorset: set of Color; 

0 


a: array [0..4] of Color; 

10 


r: record 

11 


I: integer; 

12 


S: set of Color; 

13 


C: packed array [1..4] of char; 

14 


end; 

15 

10 

1 

begin 

17 

2 

for C := Red to Green do A[ord(C)] := C; 

18 

4 

Colorset := [Red, Tellow..Green]; 

10 

5 

R.I := 123; R.S := [Orange. Green]; R.C := 'TEST 1 ; 

20 


end. 


••• lo lines with errors detected ••• 

m sum 

Pascal Debugger 73.00 — 20-Iot-1003 
Debugging prograa COLOR 

> fi 

> IIA1 

RED ORAIGE TELLOV BLUE GREER 

> All! ;» Red: Af4l := Red: 1(A) 

RED RED TELLOV BLUE RED 


4-15 


Updated January 1085 








Pascal-2 VJ.l/RT-11 Debugger Guide 


> Kfoiorm) 

[RED.TELLOl. .GREO] 

> Colortet : = [Red..Greeal; KColortet) 

[RED..GREE1] 

> HBl 

I: 123 

S: [0R11GE.GREE1] 

C: TEST 

} R.I := 321: R.S := Coloreet; fOO 

I: 321 

S: [RED..GREE1] 

C: TEST 


> 
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Informational Commands 

Informational commands show data being maintained by the Debugger. The D command shows 
the current breakpoints y user-defined macros, and variables being watched. The L command shows 
selected parts of the program listing, so that you won’t have to reprint the listing each time you 
revise your program. 

Ds Display Parameters 

The D command displays all breakpoints, user-defined macros, and the variables being watched; it 
also shows any commands associated with each. Breakpoints are set with the B command. Macros 
are stored Debugger commands created by the M command and executed by the 1 command. The ? 
command is used to set variable watches. (See the respective sections for details on these commands.) 

See the ROTAT.PAS example in “Running the Debugger” and the example after the C command. 

L 9 L()i List Source Lines 

The L command uses the statement numbers in the listing file of your program to list portions of 
the source program. The L command allows you to list individual statements, parts of procedures, 
or entire procedures. 

When a breakpoint is set at a statement with B(), the Debugger prints only the first line associated 
with the statement. The History command H also prints only the first line of the statement. The L 
command, in contrast, prints all lines containing the statement. 

The L command with no parameters lists the current procedure. You may list any other procedure 
by giving the procedure name enclosed in parentheses. For example, LQiAII) lists the body of the 
main program. 

The command L (proc, stmtnum) lists a single statement, where proc is the name of the procedure 
and stmtnum is the number of the statement to print. 

You also may list sections of the program starting or ending at a particular statement by specifying 
a line count after the statement number. For example, L(MAII,1,10) lists the first ten lines of the 
main program. 

The general form of the command is: 

} L (proc.stmtnum.count) 

where proc and stmtnum describe a statement in the program. A positive count prints that many 
lines starting at the statement specified and moving forward. A negative count causes the Debugger 
to list statements up to and including stmtnum. (The listing of source lines in external functions and 
procedures requires a slightly different form of the L command. See “Debugging External Modules” 
later in this guide for details.) 

This example lists 5 lines beginning with the first statement of procedure ROTATE: 

> LQta tftta JLgi. 

14 1 begin 

15 2 for I := First to Last do 

15 3 All] :* A[I ♦ 11; 

17 4 A[Last] := A[First]; 

18 5 write ('Rotated first: 1, 1 thru Mast: l,' s> ); 
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This example lists 2 lines leading np to and including the 4th statement of procedure Botate: 

> L(Botate.4.-2) 

16 3 All] := All ♦ 1]; 

17 4 A[Last] := A[First]; 

When you list an entire procedure, the Debugger attempts to include the procedure heading and 
local variable declarations in the listing. However, this header information is only used by the Pascal 
compiler, so the Debugger has to estimate where the procedure header information is located in the 
listing file. As a result, the Debugger may not always print the complete header information or may 
sometimes print part of the preceding procedure. 

Long procedures may take some time to print. A single Control-C (*C) interrupts the listing and 
returns the Debugger to command mode. 


Utility Commands 

Utility commands allow you to define a series of commands as a macro to be executed by entering 
a single command. 

M()t Define Macro 

The M command saves you some typing when you need to issue repetitive commands. For example, 
you may need to write the value of several critical variables at different places in your program. The 
M feature lets you combine these commands under one name, then execute this group of commands 
by using the X command, explained below. You cannot pass parameters to macros. 

The format for definition of a macro is: 

> MfnameXcommandi: co mmand: command?; 

where name is any alphanumeric string containing up to 32 symbols. The X command uses name to 
identify the macro. You may place as many Debugger commands in the angle brackets ‘< >’ as fit 
on one command tine. You may delete a macro by typing M(name) with no commands. Available 
memory is the only limit on the number of macros you may define. The D command lists macro 
names and the commands associated with each name. 

See the example after the X command. 

X(): Execute Macro 

You may execute the Debugger commands associated with a macro by using the X command. The 
format is: 

> X(name) 

where name is the name of the macro. The effect of the X command is to execute the Debugger 
commands defined by the M command of that name. 
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Examples of the M and X Commands 

rot botat 

Pascal Debagger ¥3.00 — 29-Iov-1903 
Debugging prograa ROTAT 

> M(DunpB)<W('T be value of ■»».!)> - -define macro 

> B(Rotate.1); C 
1 2 3 4 5 S 7 

Left.Right? 2_ft -input to ROTAT 

Breakpoint at ROTATE,1 begin 

> m(Pb»pI 1 <¥(*!=■ .!)> -define macro 

> B 

Breakpoints 
ROTATE,1 begin 
Macros 

DOMPI f(’I=M) 

DOTPI T(’The value of **\I) 

> 5 

Breakpoint at ROTATE,2 for I :* First to Last do 

} S 

Breakpoint at ROTATE.3 A[I] := A[I ♦ 1]; 

} TfDnepIl -——-execute macro 

1 = 2 

> S(4): KDunpI); KDunpl) 

Breakpoint at ROTATE,3 A[I] :* A[I ♦ 1]; 

1 = 6 

The value of I* 1345037 

> B 
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Execution Stack Commands 

The execution stack commands allow you to trace down run-time errors by examining the stack. 
The H command shows at any time a history of program execution and the current stack of active 
procedure and function calls. The I command lists the names of the parameters and local variables in 
any procedure in the execution stack. The E command allows you to change the context of the stack 
frame from the current procedure to another so you may access variables you otherwise wouldn’t be 
able to. 

H, HO t History of Program Execution 

The Debugger maintains a list of the last 50 statements executed while your program was running. 
With the H command you may review this execution history. For instance, if the program failed 
because of an error during execution (such as division by zero), the H command shows the steps 
leading to the statement causing the error. The H command with no parameters prints a list of the 
last 10 statements executed. H(n) prints the last n statements up to 50. 

The H command also lists the execution stack. Each time a procedure or function is called, a new 
entry is made at the top of the execution stack. When the procedure exits, that entry is removed 
from the top of the stack. The main program is always at the bottom of the stack. The H command 
shows the procedures that were called to get from the main program to the current procedure. H (0) 
prints just the execution stack. 

In the display, each procedure or function in the execution stack is identified by a number. This 
procedure number is used to identify procedures in the execution stack for the I and E com¬ 
mands described in following sections. (These are not the statement numbers used to identify other 
Debugger commands.) 

In the display, the '<’ character marks the current procedure. Unless the E command is used the 
current procedure is always the top procedure in the execution stack. The Debugger uses the current 
procedure to determine the local variables that can be accessed according to Pascal scope rules. 
Procedures marked with the asterisk V character are those procedures that contain the lexical 
definition of the current procedure. The parameters and local variables in the procedures marked 
by *<’ or V are the only local variables that you may look at or change directly. If you wish to look 
at local variables in other procedures in the execution stack, you must use the E command. 

See the example after the E command. 
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I, lOt Nemes of Verlebles 

The I command with no parameters lists the names of the parameters and local variables in the 
current procedure. If you are in the main program, the command displays all of the global-level 
variable names. 

I with a numeric parameter lists the names of the local variables in the procedure so numbered on 
the execution stack. These numbers are obtained via the H command, described above. 

Note that I lists the names of the local variables and parameters in any procedure or function on 
the stack, not merely the ones marked with the ‘s’. However, you cannot write or change the values 
of variables unless they are in procedures or functions marked with the *•’. 

The E command allows access to variables that you otherwise cannot access from the current 
procedure. 

See the example after the E command. 


E()s Enter Stack-Frame Context 

The Debugger normally enforces Pascal scope rules. If you stop your program in the middle of a 
procedure, you may write or modify only those variables and parameters of the procedures that 
enclose the current procedure, as described in the section on the H command. 

To look at or change local variables in procedures that are not accessible to the current procedure, 
the E command gets around the Pascal scope rules by temporarily changing the context of the current 
procedure. 

The H command numbers the procedures in the execution stack. The main program is always 1, and 
procedures called from the main program are listed as 2, and so on. If you want to examine variables 
in procedure 5 in the current execution stack, and it is not marked with an *•’ (and therefore 
not available to you from where you are), you use E(5) to temporarily enter the context of that 
procedure. 

The E command affects only debugging commands that follow it on the same command line. For 
example, to print the value of the variable I in the procedure listed as 5, you type: 

} ECS): 1(1) 

This command line makes procedure 5 the current procedure. Then, using the context of procedure 
5, the Debugger prints the value of the variable I. At the end of the command line, the current 
procedure is changed back to the top procedure in the execution stack. 

Because the I command allows you to list the names of variables in all the procedures on the 
execution stack, the following commands are equivalent: 

} ECS): ■ 

> 1151 
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Examples of the H, N, and E Commands 

Breakpoiat at CHECK.1 begla { start of cheek > 

> H(5) -—-—-list last 5 statements executed 

Program execution history: 


AIALTZEMOTE,9 
AIALTZEMOVE.10 
AIALTZEMOVE,14 
AIALTZEMOVE,15 
CHECK.1 begin 


Vacant[Target] : s false; 
if CentralSquares[Target] then 
PoisibleMoves := PossibleMoves«l; 

Check(4); Check(5); Check(-4); Check(-5); 
{ start of check > 


Procedure execution stack 


8< CHECK,1 begin { start of check > 

7* AIALTZEMOVE, 15 Check(4); Check(5); Check(-4); Check(-5); 
6* AIALTZE.12 AnalyzeMoTe(4,I); AnalyzeMoTe(6,I); 

5* EVALUATEBOARD.4 Analyze; 

4 GEIMOVE.15 EvaluateBoard(I*,Turn); 

3 MOVEPIECE.Q if MovesAllowed then GenMove(I, J); 

2 EZPA1D.11 if Color[Vho]-Turn then MovePiece(I,I,0,0); 

1« MAI1,8 Expand(Root.True); 


> j| -——---local names 

DIRECTIOI SRC DST F 

> if7) -—-names in frame 7 

DIRECTIOI I SAFE IASKIIG TARGET THRT 

) fill - -names in frame 4 

I J I OLDPIECE 

) Ef7): Ifl) ——- change context to frame 7, write value 

14 

) Ef4): 1(1) - change context to frame 4, write value 

27 

> E(4): B(0) 


Procedure execution stack 
8 CHECK,1 begia { start of check ) 

7 AIALTZEMOTE,16 Check(4); Check(5); Check(-4); Check(-5); 
6 AIALTZE.12 AnslyzeMove(4.I); AnalyzeMovefS.I); 

5 EVALUATEBOARD,4 Analyze; 

4< GEIMOVE,15 EvaluateBoard(I*,Turn); 

3* MOVEPIECE.Q if MovesAlloved then GenMovefl,J); 

2* EXPAID,11 if Color[fho]=Turn then MovePiecefl.1,0,0); 
is MAII,8 Expand(Root,True); 
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Stepping Through a Debugger Session 

You seldom use only s single Debugger command at any one session, so no single-command example 
can demonstrate the context in which certain commands are used nor can it demonstrate all of 
the ways in which certain commands relate. Our approach, therefore, is to step through a sample 
program to demonstrate some of the common commands in a problem/example context. 

In previous sections of this guide, several examples of run-time errors occurring in the execution of 
ROTAT.PAS were demonstrated. Let’s begin this debugging session by and running the program 
and taking a closer look at what is going wrong. 

■ B PASCAL 
s BOTAI/DEBUQ 

■ LIU BOTH.ST;PASCAL 

Pascal Debugger T9.00 — 29-Iov-1989 


Debugging progran ROTAT 

> 

After the Debugger has taken control of the program, we instruct it to go (G), then we enter the 
starting point (2,6). 

> fi 

1 2 9 4 6 6 7 
Left,Right? 2_ft 

Rotated 2 thru 6*1946697 


The problem we noted earlier persists. Our starting number in the rotation is apparently incremented 
by 1 each time the program is run. In this case, the second 3 in our rotated sequence should be 2. 
With the L command, we now list the part of the main program that initializes the I array, from 
this, we can choose a location for a breakpoint once the array is initialized. 


} Ltott.l.tt 

21 l 

22 2 

29 9 

24 6 

26 7 

) P(mU.6). 

> £ -- 


-list 5 lines of main program 

begin { Main progran > 
for I :■ 1 to Arraylea do 
begin l[I] :* 1; vrite(I:2); end; 
uriteln; write(’Left,Right? '); 
readln(Left, Right); 

. .— -set breakpoint at MAII.6 

-—-begin execution 


1 2 9 4 6 6 7 


Breakpoint at MAII.6 uriteln; write(’Left,Bight? ’); 

> f (iLgll - -write value of V[8] 


6 


(Note the way in which the Debugger counts statements when more than one is placed on a line, as 
on line number 24 above. Though not explicitly listed, the second statement on line 24 is statement 
number 6 and must be identified as such.) 

Examination of the array 1 at this breakpoint shows the array to be correct; the change to the value 
of the variable must be occurring somewhere else. Using the ? (watched variable) command, we tell 
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the Debugger to stop the program whenever I [6] is changed. 

} V (1 ffll) -—-watch for changes of value of I [6] 

} £ -----continue execution 

Left,Right? -—-input to ROTAT 

The valne of *l[6]* vas changed by the statement: 

ROTATE,3 A[I] : = A[I ♦ 1]; 

Old value: 6 
lev value: 7 

Breakpoint at ROTATE,4 A[Last] := A[First]; 

> 

This is an expected change based on the algorithm being used in the rotation. Our last number 
is first incremented by 1 before being replaced by the first. Therefore, we continue to watch the 
variable. 

> £ 

The value of *l[6] a vas changed by the stateaent: 

ROTATE,4 A[Last] := A[First]; 

Old value: 7 
lev value: 3 

Breakpoint at ROTATE,S write('Rotated ',first:l,' thru ',last:l, 

> If First. Last) —- write values of First and Last 

2 0 

> mi - -write values of array I 

1 3 4 5 6 3 7 

) g -——-quit the Debugger 

At ROTATE,4 the first element is assigned to the last element after the first element has already 
been changed. We must introduce a temporary variable to hold the first element value so that it 
will not be destroyed. We correct the program (adding a “temp" variable, an assignment at line 14 
and another between lines 16 and 17), then recompile with the /debug switch. Again, we use the L 
command to inspect the part of the program we changed. 

Pascal Debugger T3.00 — 29-Bov-1083 


Debugging prograa ROTAT 

} L(ROTATE. 1.6) -list 6 lines of procedure ROTATE 

14 1 begin Teap :* A[First]; 

15 3 for I := First to Last do 

16 4 A [I] := A [ I ♦ 1]; 

17 5 A [Last] :* Teap; 

18 6 vriteCRotated \first: 1,' thru '.last: l.*=*); 

19 end; 

> j -——-— begin execution 

1234567 

Left,Right? -input to ROTAT 

Rotated 2 thru 6*1345627 

} £ -——-begin execution 

1234567 

Left,Right? 3_A - input to ROTAT 

Rotated 3 thru 4*1243567 
Breakpoint at MAII,12 vritela 
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Now the program seems to be running correctly, but let’s make one more test before we’ve satisfied 
ourselves that the program is running as we want. Note that the G command restarts the program 
even after it has terminated. 

} £ - 

1 2 S 4 6 0 7 
Left.Right? JLZ 

TT2 — Fatal error at user PC*1424 
Array subscript out of bounds 

> 

The end points of a data subrange are always good places to look for run-time errors such as “Array 
subscript out of bounds,” because they are the values most likely to exceed the predefined limits. 
We begin analyzing this new error by writing the values of variables found in the line where the 
error occurred. 

> 1111 - -write the value of I 

7 

> W(Afall -——-write the value of A[8] 

Array subscript too largo 

V(A[8]) 


- begin execution 
input to ROTAT 


The limits are 1..7 

> £ —-—-quit the Debugger 

Now we can diagnose the error. We see that the limits for the array subscript of A have been exceeded 
by one. The for loop in the ROTATE procedure is likely to be looping too many times. We reduce 
the final value by 1 (last becomes last-1 in line 15) and recompile the program. When we run 
the program, we tell the Debugger to list procedure ROTATE, so that we can more closely follow the 
section of the program we changed. 

Pascal Debugger T3.00 — 29-Iov-1983 
Debugging program ROTAT 


> l ( RO TATE iLfil 

14 1 

15 3 

16 4 

17 5 

18 6 


-list 6 lines of procedure ROTATE 

begin Temp :=A[First]; 

for I := First to Last - 1 do 
All] := All ♦ 1]; 

A [Last] : = Temp; 

write(’Rotated ’.first: 1,’ thru ’.last: 1.’*’); 
-—— begin execution 


1 2 3 4 5 6 7 

Left,Right? 1_2 -input to ROTAT 

Rotated 1 thru 7* 2345671 

> £ -- quit the Debugger 


The results our program gives are now exactly what they should be. Once satisfied that the program 
is correct, we recompile it without the debug switch to reduce file and memory requirements, to 
improve execution speed, and to reinstate the walkback. 
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Debugging External Modules 

An external module consists of one or more Pascal procedures or functions written and compiled 
independently of the main program that invokes it. The Debugger’s ability to debug external modules 
allows you to fully debug an entire program, including externals, and also allows you to debug 
external procedures and functions only, in the context of a main program. 

The debugging of external procedures and functions is simply a matter of compiling the module with 
the debug and nosais switches, linking the module with the main program, and upon execution, 
supplying the module name on certain Debugger commands (see below). The debug compilation 
creates the necessary symbol table files for the module. (Remember to compile the main program 
with the debug switch, too.) Refer to “External Modules” in the Programmer’s Guide for rules on 
the use of external modules. 

As mentioned earlier, external modules cannot be debugged directly; they must be called from a 
main program. To debug an external procedure or function itself, create a short main program that 
simply invokes the procedure, then exits. Be sure to initialize any variables required of the call. Then 
compile the main program using the debug switch and task build it with the external module. 


Differences In the Commands 

This section covers only the differences in command syntax and usage; unless otherwise noted, the 

Debugger commands work as described in previous sections. 

In general, the major differences are: 

• The B, K and L commands accept the module name followed by a colon (:) as the first argument. 
These commands allow you to set and kill breakpoints and list source lines in external procedures 
and functions. The revised syntax for these commands are as follows: 

> a UnMaki&locLitmiMinlS 

> Kmodw/e: block.stmtnum) 

> L (module: block stmt num, count) 

The module name module is the name of the source file minus extension. For example, TEST is the 
module name for TEST .PAS. Block is the name of the procedure or function being referenced 
in module . The other arguments are the same as described in earlier sections. 

• When displaying breakpoint and source-line information, the Debugger includes the module 
name along with the procedure name and line number. The D command, in addition to displaying 
breakpoints, user-defined macros, and variables being watched, shows you which module is 
currently being debugged. 

• Defaults apply to the current module being debugged. To list lines, set breakpoints or kill 
breakpoints in any module but the current one, you must specify at least the module name and 
the procedure name on the commands. 

• If you try to list lines or set/kill breakpoints in an external module not compiled for debugging, 
the run-time error “can’t open file” causes the Debugger to abort trying to open the listing and 
symbol table files for that module. Of course, if you have old listing and symbol table files for 
that module lying around, the Debugger opens these files even if you did not wish to debug that 
module. In this case, if the data files do not match the source you’re using, your results may 
not be accurate. 

An example is presented in the next section. 
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Example 

To illustrate the debugging of external modules, we present a single debugging session in which 
the above commands are used. In this example, the main program ROTAT.PAS, presented earlier, 
calls the external procedure Rotate contained in XROT.PAS. (In the previous program, procedure 
Rotate was a local procedure.) 

After compiling the main program and external modules and task building them, run the program. 

• R PASCAL 
♦ ROTAT/DEBPG 

LIRK ROTAT.ROTATE.ST:PASCAL 

- ROT ROTAT 

Pascal Debugger 73.00 — 29-Iov-1983 
Debugging prograa ROTAT 

} L ——— ---defaults to main program 


14 

1 

begin { main prograa ) 

15 

2 

for I := 1 to Arrajlea do 

10 

3 

begin III] :* I; write(I: 2); 

17 

5 

writeln; write(’Left,Right? ’); 

18 

7 

readln(Left, Right); 

19 

8 

I :* 4; 

20 

9 

Rotate(Left, Right, 1); 

21 

10 

for I := 1 to Arraylea do 

22 

11 

write(1[I]: 2); 

23 

12 

writeln 

24 


end. 


} B(HAIR.7) 

> B(IROT:ROTATE. 5) <1 (TEMP)>_ 

Initially, the L command without parameters lists the main program by default because it 
in the current module being debugged. The first breakpoint command could just as easily 
B(ROTAT:MAII,7). However, the module name is not necessary because the main program is the 
current module. The second breakpoint command shows that you must supply the module name for 
modules other than the current one. With the G command, program execution begins: 

> £ 

1 2 3 4 5 0 7 

Breakpoint at ROTAT:MAII,7 readln(Left, Right); 

} £ 

Left,Right? 1_Z - input to ROTAT 

Breakpoint at XROT:ROTATE,5 A[Last] := Teap; 

1 
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Note the way the Debugger reports the breakpoints. At this point the current procedure being 
debugged is the procedure Rotate, in external module XROT. (The single T is the value of Temp 
when the breakpoint is reached.) Now the B, K and L commands default to the external procedure 
Rotate, as shown below for the L command. To list the lines in the main program, you must specify 
the module name, as shown in the second L command: 


} L 


IS 

1 begin Teap := A[First]; 

17 

3 

for I := First to Last-1 do 

18 

4 

A[I] := A[I ♦ 1]; 

IB 

6 

A [Last] :* Teap; 

20 

6 

write ('Rotated first: 1. 1 thru V 

21 


end; 

L(R0TAT:MAI1) 

14 

1 

begin { aaia program > 

15 

2 

for I :* 1 to Arraylea do 

18 

3 

begin B[I] :» I; write(I: 2); 

17 

6 

vriteln; write('Left.Right? '); 

18 

7 

readln(Left, Right); 

IB 

8 

I := 4; 

20 

B 

Rotate(Left, Right, B); 

21 

10 

for I := 1 to Arraylea do 

22 

11 

wrlte(B[I]: 2); 

23 

12 

writela 

24 


end. 

ft - 


-- display current 


last: 1. •=•); 


end; 


Current aodule: XROT 


Breakpoints 

XROT:ROTATE.5 A[Last] :» Temp; 

<I(TEMP)> 

R0TAT:MAIB,7 readln(Left, Right); 

) fl —-History command 


Program executioa history: 


XROT:ROTATE.1 
XROT:ROTATE.2 
XROT:ROTATE.3 
XROT:ROTATE.4 
XROT:ROTATE.4 
XROT:ROTATE.4 
XROT:ROTATE.4 
XROT:ROTATE.4 
XROT:ROTATE.4 
XR0T:R0TAI2,5 


begin Teap :* A[First]; 
begin Teap :* A [First]; 
for I :* First to Last-1 do 
A [I] :* A [I ♦ 1]; 

A[I] := A[I ♦ 1]; 

A[I] :» A[I ♦ 1]; 

A[I] :* A[I ♦ 1]; 

A [I] :* A [I ♦ 1]; 

A [I] := A[I ♦ 1]; 

A [Last] :* Teap; 


Procedure executioa stack 

3< XROT:ROTATE.5 A[Last] := Teap; 

2* Module: XROT 

1* ROTAT:MAII.O Rotate(Left, Right. B); 
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Debugging External Modules 


Execution continues with the C command. The K and B commands used below demonstrate the rules 
governing the setting and removing of breakpoints. Note the erroneous breakpoint command and 
the corrected command. 

} £ - - —---continue execution 

Rotated 1 thru 7= 2345671 

Prograa terminated. 

Breakpoint at ROUT:BAH. 12 vrltela 

> I (MAH. 7) -kill breakpoint 

> i 

1 2 3 4 6 0 7 

Left,Right? LI -to ROTAT 

Breakpoint at XROT:ROTATE,5 A[Last] :* leap; 

1 

} BfHAI1.7) -won’t work without the module name 

lo such stateneat la this procedure 
B(HAIR,7) 


> B(B0TAT:MAI1.7) -that’s better 

> £ 

Rotated 1 thru 7* 2346071 

} ft -—-quit the Debugger 
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Pascal-2 V2.1/RT-11 Debugger Guide 


Overlays 

The debugging of large programs is aided by the execution of two command files, EXTRAC.COM 
and either XMDBG.COM (for XM systems) or SJDBG.COM (for SJ systems), which are included 
in the distribution kit. These command files produce a much smaller load image than that of a 
non-overlaid Debugger, saving up to 6K words of memory. These command files can be executed 
with the indirect (at-sign) processor. 

The command file EXTRAC.COM extracts from the Pascal support library the modules needed for 
overlaying the Debugger against a Pascal program. EXTRAC.COM need only be executed once, at 
installation, to ensure that the necessary Debugger and support library modules are available. The 
modules are placed on the system device, with the extension .DBG. 

The command file XMDBG.COM, used in the XM environment, links your program and the Debugger 
into virtual overlays. The command file SJDBG.COM, for the SJ environment, links your program 
and the Debugger into overlays. 

After the modules have been extracted, examine and modify the link command file you wish to use, 
replacing all occurrences of FOO in the file with the name of your program. Then execute the link 
command file to create the overlaid program. The program is now ready to run. 

When debugging programs that use overlays don’t confuse the program’s existing overlay structure 
with the structure imposed by the link command file you are using. The results may be unpredictable. 


Updated January 1085 


4-30 






Appendix At Debugger Command Summary 


Appendix A: Debugger Command Summary 


B 

B (block, stmtnum) 

B (block, stmtnum) < ... > 

PDF B(module:block,stmtnum) 

B(module-.block,stmtnum)< ... > 
C 

C(n) 

D 

E(o) 

G 

H 

B(n) 

E 

E (block, stmtnum) 

K(module: block, stmtnum) 
L(proc) 

Kproc, stmtnum) 

L (proc, stmtnum, x) 

L (module: proc) 

L (module: proc, stmtnum) 

L (module: proc, stmtnum, x) 

M (name) <commands> 

I 

■ (d) 

P 

P(n) 

a 

s 

so.) 

T(TRUE/FALSE) 

¥ (variable) 

¥ (variable) < ... > 

«() 

I (name) 

variable :• value 
T 

*C (Control-C) 

‘Z (Control-Z) 


Remove current breakpoint 

Set a control breakpoint 

Control breakpoint with stored commands 

Set a control breakpoint in external module 

Set external control breakpoint with stored commands 

Continue program execution 

Continue n times 

Display breakpoints and macros 

Enter context of frame n (1 line only) 

Restart program 

Display recent history and full stack 

Display last n statements executed 

Remove all control breakpoints 

Remove specified breakpoint 

Remove specified breakpoint from external module 

List source of proc 

List statement stmtnum in proc 

List x lines beginning with statement stmtnum in proc 

List source of external module proc 

List statement stmtnum in external module proc 

List x lines beginning with statement stmtnum in external proc 

Define stored command macro 

List variable names for current frame 

List variable names for frame n 

Proceed 1 statement at current level 

Proceed n statements 

Quit Debugger 

Single-step statement 

Single-step n statements 

Enable/disable tracing 

Set data breakpoint 

Data breakpoint with stored commands 

Write list of values 

Execute named macro command 

Assign va/ue to variable 

Help (display command summary) 

Immediate breakpoint 
Exit from Debugger 
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The Pascal-2 Profiler 


The Pascal-2 Profiler can help you tune Pascal programs by detecting bottlenecks: small sections of 
code in which your program spends a disproportionately large amount of time. The Profiler counts 
the number of times each Pascal statement in your program is executed then prints a summary 
describing how many times each procedure is called and what percentage of the total statements 
executed are found in that procedure. 

To use the Profiler, you should compile your program with the profile switch. (See the Program* 
mer’s Guide for details on compilation switches.) The profile switch causes the Pascal-2 compiler 
to generate several auxiliary files. These files, which permit the Profiler to locate the statements and 
procedures in your program, are the same ones generated by the debug switch. 

The compilation and steps are shown below, using a program, CHECKR.PAS, which plays a game 
of checkers. 

•B PASCAL 

e CHECP/PBOFILE 

■ LIU CHECKR.ST:PASCAL 

Upon execution, the Profiler takes control of the program and opens the program’s auxiliary files 
created by the Pascal compiler. For large programs, there may be a short pause while the Profiler 
scans the auxiliary files to build internal data structures. 

Next, the Profiler prompts for the name of the profile output file. If you specify a disk file, the 
default file extension is .PRO. Writing a profile to the terminal is practical only for a short program. 

Compile and link the program as previously shown, then run it. 

• BUI CHECKS 

profil* ¥2.IB — 6-Feb-1983 
Profiling aodula: CHECKS 

Profile output file aaaef CHECKB -Output goes to CHECKR.PRO 

Velcoee to checkKBS -Program continues, slowly 

The Profiler counts the number of times each statement is encountered. This counting of each 
statement slows down program execution. For this reason, it may not always be possible to profile 
programs that operate in a time-critical environment. 

The Profiler generates a performance outline when the program terminates. Termination occurs 
when your program reaches the logical end of the program or when the program detects a fatal 
error condition. A Control-C (*C) interrupts the program and generates a profile at that point. 
Entering Control-C (*C)’s twice aborts the generation of the profile. 

The Profiler listing has the same two columns of numbers as the Debugger listing (one column 
numbers each line of the source program and the other gives the statement number of the first 
statement on each line), plus an extra column of numbers at the far left of the listing. 

This leftmost column lists the number of times the statement on that line is executed. If more than 
one statement appears on the line, the count applies only to the first statement on the line. To obtain 
an accurate count of each statement in the program, you can run your source program through the 
PASMAT formatter supplied with Pascal-2. The PASMAT ‘S’ directive reformats the code so that 
no more than one statement appears on each line. (PASMAT is described in the Utilities Guide.) 
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If no number is printed in the leftmost column, then that particular statement was never executed. 
You can sometimes detect logic errors in your program by scanning the profile output to find sections 
of code or perhaps entire procedures that are never executed. 


A summary of the program’s execution, procedure by procedure, appears at the end of the profile 
listing. Procedures are listed in the order they appear in your source code. Three columns of 
information are displayed for each procedure, as follows: 

Stateaeate This column lists the number of statements that appear in the definition of the 
procedure. 


Times This column shows how many times each procedure is called during program 

Called execution. 


This column has two figures. The first is the number of statements executed in the 
procedure. For example, a procedure that contains 10 assignment statements and 
is called 5 times will show 50 statements executed in the stateaents executed 
column. This direct relationship is valid only for very simple procedures. In most 
procedures and functions, loops and other control structures cause the number of 
“statements executed” to be much larger (or smaller) than you may expect at first 
glance. The second figure in this column is the percentage of statements executed 
in this procedure as compared to the total number of statements executed in the 
program. The total number of procedures and statements and the total number 
of statements executed are printed at the bottom of the procedure execution 
summary. 

The following example profile from CHECKR shows that 2.6 million statements were executed. 
(To save space, only the Procedure Execution Summary and relevant portions of the profile listing 
are shown here.) The Profiler listing shows that the program spent most of its time in only a few 
procedures. For example, the summary shows that 21 percent of the total statements executed were in 
the 15-statement procedure Check. However, Check was called 71,212 times, so that percentage does 
not seem too far out of line. More interesting is that almost half a million statements (17.63 percent) 
were executed in the procedure Initialize. This number seems excessive because the procedure 
does nothing more than initialize variables and tables each time a board position is analyzed and 
was only called 1348 times. We may have a problem here. 


Stateasats 

Executed 
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The Paseal-2 Profiler 


PROCEDURE EXECUTION SUMMART 


Procedure uaae 

atateaeata 

tiaea called 

atateaeata 

executed 

IEVI0DE 

15 

1390 

18070 

0.69* 

IIITIALIZE 

17 

1348 

459668 

17.63* 

SCA1 

32 

1348 

120580 

4.62* 

CHECK 

16 

71212 

667111 

21.76* 

ANALTZEMOYE 

40 

25362 

616325 

19.80* 

A1ALYZE 

38 

1348 

298566 

11.45* 

UVPACnODE 

54 

1348 

60660 

2.33* 

PACnODE 

23 

1348 

22768 

0.87* 

SC0REGRADIE1T 

15 

1348 

250028 

9.59* 

SCOREBOARD 

54 

1348 

99228 

3.80* 

ETALUATEBOARD 

5 

1348 

6740 

0.26* 

DISPLATBOARD 

22 

41 

5453 

0.21* 

EXTRACT 

18 

715 

7328 

0.28* 

KILL 

11 

1388 

13621 

0.62* 

PRUIE 

3 

219 

657 

0.03* 

I1IT 

165 

1 

1575 

0.06* 

COMPARE 

14 

4128 

24768 

0.95* 

IISERT 

26 

1843 

40490 

1.65* 

DUMPIODE 

11 

0 

0 

0 . 00 * 

GEIMOTE 

18 

1273 

17822 

0.68* 

CEBJUMP 

53 

75 

4389 

0.17* 

MOTEPIECE 

12 

1790 

32100 

1.23* 

EXPAID 

17 

239 

20372 

0.78* 

POSITIOICURSOB 

2 

0 

0 

0 . 00 * 

MAKEMOTE 

55 

306 

7371 

0.28* 

DESCEND 

26 

197 

3592 

0.14* 

FULLEXPA1D 

46 

127 

6046 

0.23* 

READMOTE 

6 

2 

12 

0.00* 

DECODE 

12 

0 

0 

0.00* 

READFILE1AME 

9 

0 

0 

0.00* 

GETUSERMOVE 

108 

1 

90 

0.00* 

MAIM 

91 

1 

2406 

0.09* 


There ere 1032 stateaents la 32 procedurea la thia prograa. 

2607836 ateteaeata vere executed duriag the profile. 

Because we suspect a problem in the procedure Ialtiallze, we examine the profile output associated 
with that procedure. The first column of numbers is the statement execution count. The second 
column is the line number of the statement in the source file. The third column of numbers is 
the statement number of the statement. (This statement number is the same number used by the 
Debugger.) 
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The Profiler listing for procedure Initialize is: 



173 


procedure Initialize; 


174 


var 


175 


I: integer; 

1348 

178 

1 

begin < start of Initialize > 

1348 

177 

2 

for I :* - 5 to 49 do begin 

74140 

178 

3 

Tacant[I] :* false; 

74140 

179 

4 

Friend[I] := false; 

74140 

180 

5 

Eneay[I] :* false; 

74140 

181 

6 

FrlendKlng[I] := false; 

74140 

162 

7 

EneayKing[I] :* false; 

74140 

183 

8 

Protected[I] :« false; 


184 


end; 

1348 

186 

9 

Pinned :* 0; 

1348 

188 

10 

Threatened :* 0; 

1348 

187 

11 

Uaobil :* 0; 

1348 

188 

12 

Denied := 0; 

1348 

189 

13 

BlackPleces :* 0; 

1348 

190 

14 

VhitePieces :* 0; 

1348 

191 

15 

Center :* 0; 

1348 

192 

18 

MoreSystea :» 0; 

1348 

193 

17 

EneayHasKings :« false; 


194 


end; { of Initialize > 


In statements 3 through 8, a for loop is initializing several Boolean arrays of the same type. Each 
assignment inside the loop is executed 74,140 times—a very inefficient way to initialize these arrays. 
Instead, we can modify the program to initialize one array, then assign that array to the other arrays 
to be initialized. 

The effect of the modification is apparent in this new profile of the same section of code. 



173 


procednre Initialize; 


174 


rar 


175 


I: integer; 

1732 

176 

1 

begin { start of Initialize > 

1732 

177 

2 

for I := - 5 to 49 do begin 

96260 

178 

3 

Tacant[I] :» false; 


179 


end; 

1732 

180 

4 

Friend : s Vacant; 

1732 

181 ■ 

6 

Enemy := Vacant; 

1732 

182 

6 

FrlendKing :* Vacant; 

1732 

183 

7 

EneayKlng ;= Vacant; 

1732 

184 

6 

Protected :* Vacant; 

1732 

185 

9 

Pinned :* 0; 

1732 

186 

10 

Threatened :* 0; 

1732 

187 

11 

Uaobil :» 0; 

1732 

188 

12 

Denied :* 0; 

1732 

189 

13 

BlackPleces : s 0; 

1732 

190 

14 

VhitePieces :» 0; 

1732 

191 

15 

Center :* 0; 

1732 

192 

16 

MoreSystea := 0; 

1732 

193 

17 

EneajHasKings :* false; 


194 


end; { of Initialize > 
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The result is clear: Instead of six assignments, each of which is executed 74,140 times, we have 
one assignment executed 95,260 times. (The execution numbers differ from the sample execution 
summary because the CHECKR program uses random numbers to play a different game each time 
it is run.) Overall, the Program Execution Summary shows that the time spent in the Initialize 
procedure has dropped from 17 percent to 4 percent of the total program. By rewriting six lines, we 
have improved performance by 11 percent. 

Further, the number of times Statement 3 is executed can be reduced by the use of a global array 
initialized only once at the start of the program. 

Similar optimizing techniques may be applied to other parts of the program. The Procedure Execution 
Summary indicates where the effort cam best be applied—and where it cannot. For example, the 
program spent 21 percent of its time in the 15-statement procedure called Check. The trimming 
of even one statement from this procedure could significantly improve performance. On the other 
hand, one of the larger procedures in the CHECKR program is Cemjuap, containing 53 statements. 
The program, however, spent much less than 1 percent of its time in this procedure. Even by eliminat¬ 
ing this procedure completely, we would improve program performance by only a trifling amount. 

Two warnings: First, a statement count is not identical to “work.” Complex statements take more 
time to execute than simple statements and this time is not measured. Second, the percentages 
shown in the atateaantn executed column are percentages of execution counts, not execution time. 
For compute-bound programs such as CHECKR, the execution percentage closely approximates the 
percentage of time spent in the procedures. I/O-bound programs, however, may spend much of their 
execution time opening files or waiting for the disk to transfer information to memory. In this case, 
the execution count percentages may differ significantly from the real amount of time spent in the 
procedures. 
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Introduction to the Utilities Guide 

The Pascal-2 utilities are a collection of programs designed to make life easier for programmers. Some 
of the utilities, such as the formatters, are designed to lessen the tedium in formatting programs 
and program documentation. Other utilities, such as the cross-reference programs, can help analyse 
code. Still other utilities, such as the MACRO package or the string-processing package, extend the 
capabilities of Pascal-2. 

Each section of the Utilities Guide describes the particular utility in detail and includes examples 
on its use. Briefly, however, the Utilities Guide contains the following: 

Two Program Formatters: PASMAT, a sophisticated formatter with a number of options; PB, a 
simple formatter designed to assist, rather than supplant, your own formatting of program text. 

Two Cross-Reference Programs: XREF, which cross-references the variables in your program or 
words in a text file; and PROCREF, which cross-references the procedures in your program. 

Dynamic String Package: STRING.PAS, a set of procedures designed to help you manipulate charac¬ 
ter strings. 

MACRO Package: PASMAC, which helps to interface MACRO-11 routines with Pascal-2 programs. 

Text Formatter: PROSE, which provides a number of formatting options for the production of 
computer-related documentation. 
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PASMAT: A Pascal-2 Formatter 


PASMAT generates a standard format for Pascal code. PASMAT will accept standard Pascal and the 
language extensions in Pascal-2. PASMAT accepts full programs, external procedures, or groups of 
statements. A syntactically incorrect program will cause PASMAT to abort and to cease formatting 
the output file. 

PASMAT’s default formatting requires no control from you. The best way to find out how the for¬ 
matting works is to try it and see. In addition, PASMAT’s formatting directives give you considerable 
control over the output format when you wish. 


Overview of Capabilities 

PASMAT has these capabilities: 

• The program may be converted to uniform case conventions, under the control of the user. 

• The program is indented to show its logical structure and to fit into a specified output line 
length. 

• Comment delimiters are changed to braces (O). 

• If requested, the break character (_) will be removed from identifiers for use at installations 
that do not support the break character. 

• If requested, the first instance of each identifier will determine the appearance of all subsequent 
instances of the identifier. 

• All non-printing characters are removed; this feature is useful after certain editing bugs. 

PASMAT handles comments, statements, and tables in the following manner: 

Comments 

PASMAT’s rules allow you to achieve almost any effect needed in the display of comments. 

• A comment standing alone on a line will be left-justified to the current indention level, so that it 
will be aligned with the statements before and after it. If it is too long to fit with this alignment, 
it will be right-justified. 

• A comment that begins a line and continues to another line will be passed to the output 
unaltered, indention unchanged. This type of comment is assumed to contain text formatted 
by the author, so it is not formatted. 

• If a comment covered by one of the above rules will not fit within the defined output line length, 
the output line will be extended as necessary to accommodate the comment. Once formatting 
is complete, a message to the terminal will give the number of times the width was exceeded 
and the output line number of the first occurrence. 

• A comment embedded within a line will be formatted with the rest of the code on that line. 
Breaks between words within a comment may be changed to achieve proper formatting, so 
nothing that has a fixed format should be used in such a comment. If a comment cannot be 
pr.operly spaced so that the line will fit within the output length, that line will be extended as 
necessary. Once formatting is complete, a message to the terminal will give the number of times 
the width was exceeded and the output line number of the first occurrence. If no code follows 
a comment in the input line, then no code ■yvill be placed after the comment in the output line. 
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Overview of Capabilities 


Statement Bunching 

The normal formatting rule for a case statement places the selected statements on a separate line 
from the case labels. The B directive (see below) tells the formatter to place these statements on 
the same line as the case labels if the statements will fit. 

Similarly, the rules for if-then-else, for, while, and with place the controlled statements on 
separate lines. The B directive tells the formatter to place the controlled statement on the same line 
as the statement header if the statement will fit. 


Tables 

Many Pascal programs contain lists of initialization statements or constant declarations that are 
logically a single action or declaration. You may want these to be fit into as few lines as possible. 
The S directive (see below) allows this. If this is used, logical tab stops are set up on the line, and 
successive statements or constant declarations are aligned to these tab stops instead of beginning on 
new lines. 

At least one blank is always placed between statements or comment declarations, so if tab stops are 
set up at every character location, statements will be packed on a line. 

Structured statements, which normally format on more than one line, are not affected by this 
directive. 


Using PASMAT 

Invoke PASMAT with the following command: 

. R PASMAT 

* output-£le = input-file /options = H directives" 
input-file: 

The Pascal source file being reformatted. PASMAT accepts only one input file. The 
default file extension for both input and output is .PAS. 

output-file: 

The reformatted Pascal source file. If output-file is omitted, the output file receives the 
same file name and extension as the input file and becomes the latest version of that file. 

options = m directives 0 : 

Settings for formatting directives. The options switch is optional. It may be ab¬ 
breviated to o and may be placed anywhere on the command line. Though the *=’ 
is shown as the switch separator, a colon (:) may also be used between the op¬ 
tions switch and the directives. When specified on the command line, directives 
must be placed in quotes as shown. The directives field will be scanned as though 
the directives were in a Pascal comment at the start of the source program. 
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PASMAT: A Pascal-2 Formatter 


Formatting Directives 

Formatting directives may be specified either by an options switch on the command line or by a 
special form of the Pascal comment structure. 

Formatting directives are of two breeds: switches that turn on with the plus sign (+) and off with 
the negative sign (-) (e.g., R+ and L-); or numeric directives of the form T=5. Multiple directives are 
separated by commas (e.g., R+,L-). Blanks are not allowed within a directive. Case is ignored: R+ is 
the same as r+ in a directive. 

By definition (and by default), certain directives override other directives, such as the L directive 
overriding the U and R directives. Therefore, when turning on a directive, you must turn off any 
directive that overrides it. For example, suppose you want all Pascal reserved words in upper case. 
In addition to setting R+, which specifies upper case, you must also turn off the L directive with L-. 
See the second example under “PASMAT Examples.” 

The following example shows a program named PROG.PAS being formatted with a command-line 
directive that sets the switch B on, R off and the numeric directives 0 to 72 and T to 5. 

. R PASMAT 

♦ PROG/OPTIONS^B*. 0=72, T=5, R- M 

If used in the program text as part of an embedded Pascal comment, format directives are placed 
within square brackets that, along with any other comments, are placed within the standard Pascal 
comment braces. A compiler directive (e.g., $nomain), if present, must begin any comment containing 
a PASMAT directive. In this case, the PASMAT directive may come before or after any other text: 

{$ compiler-directives text [ directives ] text > 

If no compiler directive is present, the PASMAT directive must begin the comment: 

< [ directives ] text} 

The following embedded directive has the same effect as the command-line directive shown above. 

{ [b+,o=72,t=5 , r-] > 

The PASMAT formatting directives are: 

A (Default A-) Adjusts each identifier so that the first instance of the identifier determines 
the appearance of all subsequent instances of the identifier. This facility standardizes the 
use of upper-case and lower-case characters and the break character (_) in program text. 
This directive overrides the U directive. 

B (Default B-) Specifies that the statements following a then, or else, for, with or while 
will be put on the same line if they will fit. The statement following a case label will be 
put on the same line if it fits. The result is a shorter output, which may be easier to read 
but which also may be harder to correct. 

C (Default C-) Converts leading blanks to tabs on output. 

F (Default F+) Turns formatting on and off. This directive goes into effect immediately after 

the comment in which it is placed and can save carefully hand-formatted portions of a 
program. 

K (Default K-) Converts the Pascal-1 else clause in a case statement to otherwise as used 
in Pascal-2. 

L (Default L+) Specifies that the case of identifiers and reserved words be a literal copy of the 
input. This directive overrides the U and R directives and is disabled by the P+ directive. 
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Formatting Directives 


M (Default M+) Converts all alternate symbol representations to the standard form. Otherwise, 
all symbols are left as they are in the text. The nonstandard comment brackets /* ... */ 
are always converted, either to braces or, in the case of M-, to (* ... *). 

N (Default N-) Inserts no new lines into the output unless they are required to make the lines 
fit. This directive just indents the source, keeping the line structure set up by the user. If a 
line exceeds the output length, it will be broken at the best place available, but the results 
may not be what you want. Look things over carefully after using this option. 

0 (Numeric directive, default 0=78) Specifies the width of the output line. The maximum 
value allowed is 132 characters. If a particular token will not fit in the width specified, 
the line will be lengthened accordingly, and a message at the end of the formatting will 
give the number of times the width was exceeded and the output line number of the first 
occurrence. 

P (Default P-) Sets “portability mode* formatting, which removes break characters (_) from, 
identifiers. The first letter of each identifier, and the first letter following each break 
character, will be made upper case, while the remaining characters will be in lower case. 
This directive overrides the L and U directives. The R directive sets the case of reserved 
words. 

Warning: Pascal-2 considers break characters significant; User.DoesThis is one identifier 
and UserDoes.This is another. Take care when using this directive that you do not make 
two different identifiers the same: UserDoesThiB and UserDoesThis. 

R (Default R-) Specifies that all reserved words will be in upper case. With this off, reserved 
words will be in lower case. The L directive overrides the R directive. When using R+ 
you must also use L- to turn off the overriding directive. See the second example under 
“PASMAT Examples." 

S (Numeric directive, default S=l) Specifies the number of statements per line. The space 
from the current indention level to the end of the line is divided into even pieces, and 
successive statements are put on the boundaries of successive pieces. A statement may take 
more than one piece, in which case the next statement again goes on the boundary of the 
next piece. This is similar to the tabbing of a typewriter. 

Any statement requiring more than one line will not be affected, but may cause unexpected 
results on following statements. This directive only affects the constant declaration and 
statement portions of the program and is intended for use in initializing tables. The default 
value of 1 provides normal formatting. 

T (Numeric directive, default T=2) Specifies the amount to “tab" for each indention level. 
Statements that continue on successive lines will be additionally indented by half the value 
of T. 

U (Default U-) U+ specifies that identifiers are converted to upper case; U- specifies that they 
will be converted to lower case. The L, P and A directives override this directive. When 
using U+ you must also use L~ to turn off the L directive. Also, make sure the P directive 
is off (P-, the default). 
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Limitations and Errors 

PASMAT is limited in these ways: 

• The maximum input line length is 132 characters. 

• The maximum output length is 132 characters. 

• Only syntactically correct statements are formatted. A syntax error in the code will cause the 
formatting to abort. An error message will give the input line number on which the error is 
detected. The error checking is not perfect, and successful formatting is no guarantee that the 
program will compile. 

• The number of indention levels handled by PASMAT is limited; PASMAT will abort if this 
number is exceeded — a rare circumstance. 

• If a comment will require more than the maximum output length (132) to meet the rules given, 
processing will be aborted. This situation should be even rarer than indention-level problems. 

• When it aborts, PASMAT attempts to copy the rest of the file. You should, however, recover a 
copy of the source file and inspect the PASMAT-generated copy carefully; we cannot guarantee 
that PASMAT will recover all the text for every error condition. 





PASMAT Examples 


PAS MAT Examples 

To show how the various PASMAT options work together, we will take the sample program that 
follows and show how it appears after reformatting with two different sets of options. 

program Efact(output); 

{ Compute an approximation for E from its Taylor series > 

{ The Nth term in the series is 1/(N!) > 

var E, series.term: real; N: integer; 

begin 

{ set initial conditions > 

E := 1.0; N := 1; SeriesTerm := 1.0; 

{ loop to approximate E; quit vhen the series sum stops changing > 
repeat 

E := E + seriesterm; 

{ compute next term of series > 

N := N + 1; seriesterm := seriesterm / N; 
until E = (E + SeriesTerm); 

writelnClith 1 , n: 1, 1 terms, value of e is 1 , e: 18: 15); 
end. 

First we reformat the program using the standard indention of text and comments. We use the 
output directive on the command line to specify the width of the output line, and we specify a short 
line width to illustrate the right-justification of long comments. 

The program is formatted with the commands: 

. R PASMAT 

♦ EFACT/QPTI0NS= I, 0=66 11 

Program text after formatting: 
program Efact(output); 

{ Compute an approximation for E from its Taylor series > 

{ The Nth term in the series is 1/(N!) > 

var 

E, series.term: real; 

N: integer; 

begin 

{ set initial conditions > 

E := 1.0; 

N := 1; 

SeriesTerm := 1.0; 

{ loop to approximate E; quit vhen the series sum stops changing > 
repeat 

E := E + seriesterm; 

{ compute next term of series > 

N := N + 1; 

seriesterm : = seriesterm / N; 
until E - (E + SeriesTerm); 

vriteln('With 1 , n: 1, 1 terms, value of e is 1 , e: 18: 15); 
end. 

The second example illustrates embedded PASMAT commands. We have altered the original program 
by inserting the text {[A+,L-,R+]> before the first line. The directive A+ changes each identifier to 
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match the appearance of the first use of that identifier. (Notice the variant forms of series jterm 
and E in the original program.) The directives L- and R+ together turn off the literal reproduction 
of the reserved words and make them upper case. The program is formatted with the commands: 

. R PASMAT 
♦ EFACT 

Program text after formatting: 

{[A+,L-,R+]> 

PROGRAM Elact(output); 

{ Compute an approximation for E from its Taylor series > 

{ The Nth term in the series is 1/(N!) > 

VAR 

E, series.term: real; 

N: integer; 

BEGIN 

{ set initial conditions > 

E := 1.0; 

N := 1; 

series.term := 1.0; 

{ loop to approximate E; quit vhen the series sum stops ch an g in g } 

REPEAT 

E := E + series.term; 

{ compute next term of series > 

N := N + 1; 

series.term := series.term / N; 

UNTIL E = (E + series.term); 

writeIn(‘With 1 , N: 1, 1 terms, value of e is 1 . E: 18: 15); 

END. 


c 
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PB is designed on the premise that a formatting program can’t do everything, that formatting 
requires an understanding of the meaning of a program. Thus, PB is meant to assist, rather than 
replace, the manual arrangement of program format. The simple transformations performed by PB 
reduce the tediousness of formatting program text and help ensure consistency within a variety of 
personal formatting styles. 

PB can be used on code as it is being developed, even code that is incomplete or incorrect. You write 
a program, or program fragment, to some level of detail, then run it through PB. You can then edit 
the resulting code to alter its meaning or improve its appearance, and use PB again. This cycle can 
be repeated as the code progresses from initial idea to working program, and later as the program 
is “maintained.” 

Text produced by PB usually looks much like the input. Each input line is transformed into a single 
output line containing essentially the same text; within the code on a line the spacing is the same; 
and simple statements that continue onto multiple lines stay lined up. 

PB adjusts program format to be consistent with the syntactic structure of Pascal. Statements at the 
same nesting level line up, and indention increases with the nesting level. Where possible, trailing 
comments are lined up with one another. Keywords and identifiers in the text are altered to match 
the capitalization style of their first occurrence (which may be in an included file). 

Using PB 

You invoke PB with the following command: 

. R PB 

* output-6ie = input-files /switches 
input-SJes: 

The Pascal source files being reformatted. The default file extension is .PAS. Multiple 
files, if specified, are separated by commas. Multiple files are concatenated to produce 
the output file. 

output-Sle: 

The reformatted Pascal source file. The default file extension is .PAS. If output - 
SJe is not specified, the output file will be created with the same file name and 
extension as the last input file and becomes the latest version of the file. 

switches : Command-line switches used to adjust PB formatting. These switches must be placed 
after the input file names on the command line. Switches may be either or both of 
these: 

The indent: num switch specifies the number of columns (num) in an indention step 
(the space that text is shifted when the nesting level changes). The default setting is 
2; larger values make the separation between levels clearer, but may force text past 
the right margin. 

The comment: num switch specifies the column (num) to which trailing comments are 
indented. The default setting is 33; this value works well when trailing comments are 
used primarily to annotate declarations. 

The switches may be abbreviated to two letters. Multiple switches are separated by a 
slash 7’. 
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Example 


This example illustrates the functions provided by PB. The example also shows a particular develop¬ 
ment style, discussed above, to which PB is suited. 

We start with the program at an intermediate stage in its development. Some new code has just 


been added. Notice that the new code is not indented; it is broken into reasonable lines, but we will 


let PB do the rest of the formatting. 

var I, X: integer; 
begin 
X := 1; 

for I := 1 to n do begin 
repeat 
x := x + 1; 

prim := x is a prime number; 
until prim; 
write(X); 

end; 

end. 

Processing by PB gives this result: 

var I, X: integer; 
begin 
X := 1; 

for I := 1 to n do begin 
repeat 

X := X + 1; 

prim := X is a prime number; 
until prim; 
write(X); 
end; 



end. 


The indent changes at most one step from line to line. When control constructs appear one per line 
(the repeat statement, for instance) each causes the indent to increase by one step, but when a 
second one appears on a line it has no effect on indention. In the example, this has been used to cut 



the “noise” from begin.. .end brackets. 


Notice a couple of things at this stage. First, PB does not know much about Pascal language syntax 
(note the phrase “X is a prime number”). Second, PB uses the first instance of a word, regardless of 
context, for its capitalization style (you can set the style for an identifier by adjusting its declaration, 
since the declaration of an identifier must precede its use). 
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Of course, the program is not yet complete, nor does it contain any comments. The following is 
closer to a final version. 

type Index = l..n; 
var 

X: integer; { number being tested lor primality > 

j, { count of primes found > 

k, { trial divisor > 

lim: index; { last divisor to test > 

Prim: boolean; { 'true 1 until a divisor is found > 

P: array[index] of integer; { P[I] = Ith prime number > 
begin 

P[l] := 2; X := 1; Lim := 1; 
vrite( 1 2'); 

for J := 2 to n do begin 
repeat 

X := X + 2; 

if sqr(P[Lim]) <= X then Lim := Lim + 1; 

K := 2; Prim := true; 

while Prim and (K < Lim) do begin 

Prim := (X mod P[K]) <> 0; 

K := K + 1; 
end; 

until Prim; 

P[J] := X; write (X); 
end; 

end. 


Processing by PB gives: 


type Index = 1..n; 


var 

X: integer; { 

j. * < 

k, { 

lim: Index; { 

Prim: boolean; { 


P: array[Index] of integer; { 
begin 

P[l] := 2; X := 1; lim := 1; 
write('2'); 


number being tested for primality > 
count of primes found > 
trial divisor > 
last divisor to test > 

'true 1 until a divisor is found > 
P[I] = Ith prime number > 


for j := 2 to n do begin 
repeat 

X := X + 2; 

if sqr(P[lim]) <= X then lim := lim + i; 
k := 2; Prim := true; 
while Prim and (k < lim) do begin 
Prim := (X mod P[k]) <> 0; 
k := k + 1; 


end; 

until Prim; 

P[j] := X; write (X) ; 
end; 

end. 
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The comments have been moved to the right, where they stand apart from the program code and 
line up for easier reading. If we had wanted to keep a comment attached to the code, we could have 
placed it in front of the final comma or semicolon on its line (then it would not be a trailing comment 
and would be treated as part of the text), or placed it on a line by itself (where it would be aligned 
at the prevailing indent). 

Detailed Formatting Rules 

Indention is directed by the nesting of control constructs in the program text. Generally, when the 
nesting level increases, the indent increases by the indention step; when a nesting level ends, the 
indent reverts to that of the surrounding nesting level. A change of indention at the beginning of a 
line takes effect immediately; otherwise, it takes effect on the next line. The exceptions to the rules 
are: 

• The start of a new nesting level does not change the indent if it begins on the same line as the 
surrounding level. 

• When a line begins with a statement label, the indent for that line is decreased by the indention 
step. 

Normal indention rules do not apply when a simple statement or clause continues across multiple 
lines. In these cases, the initial line is indented normally, but the following lines are arranged to 
preserve their alignment with the initial line. Changes of indention within continued lines take effect 
after the last continuation. 

A similar adjustment occurs when a comment continues across multiple lines. When a trailing 
comment is continued, the following lines stay aligned with the initial part of the comment, but 
not necessarily with the rest of that line (a trailing comment may shift in relation to the rest of the 
line). 

The following constructs affect the indention level: 

• A program-declaration, procedure-declaration or function-declaration is arranged so that the 
heading , the keyword introducing a label-declaration-part, const-definition-part, type-definition- 
part, or variable-declaration-part, and the body are all at the same indention level. The list of 
declarations within a label-declaration-part, const-definition-part, type-definition-part, variable- 
declaration-part, or procedure-and-function-declaration-part is set one indention step deeper. 

• The component-type of an array-type or file-type, and the base-type of a set-type are indented 
one more step. Within a record-type the held-list is indented another step, the list of variants 
within the variant-part is indented an additional step, and the held-lists within individual 
variants are indented yet another step. 

• The statement-sequence within a compound-statement is indented an additional step. 

• The controlled statement within a for-statement, if-statement, else-part, while-statement or 
with-statement, and the statement-sequence within a repeat-statement are indented another 
step. Within a case-statement the list of case-list-elements is indented one more step, and the 
controlled statement of each case-list-element is indented an additional step. 










XREF: A Pascal-2 Cross-Reference Lister 


XREF produces a cross-reference listing of the identifiers in a Pascal program. XREF is helpful 
when debugging new programs or when modifying existing ones. The output shows the use of each 
identifier in the program, which is beneficial when you’re working with medium to large programs. 

Each identifier is listed, along with an entry for each reference to that identifier. Each entry consists 
of the line on which the reference occurs, plus an indication of whether the reference is a declaration 
or assignment. 


Using XREF 

You invoke XREF with the following command: 

. R XREF 

» output-file = input-file /switches 
input-file: 

The Pascal source file being cross-referenced. The input file has a default exten¬ 
sion of .PAS. XREF accepts only one input file. 


output-fle: 

The cross-reference file. The output file has a default extension of .CRF. Output- 
fie and the *=’ separator are optional. If they are omitted, an output file with the 
same name as the input file, and having the default extension, is placed in the default 
directory. 

switches: Command-line switches. Switches may be either or both of these: 

The list switch generates a listing of the input file before the cross-reference. This 
listing includes line numbers and a flag character (c) indicating multiple line comments 
and strings. The flag character makes it easier to locate certain bugs that cannot be 
easily diagnosed by the compiler. 

The width: num switch specifies the page width for the cross-reference listing, where 
num is the number of characters across. The default is 132. 

The switches may be abbreviated to one letter. Multiple switches are separated by a 
slash 7’. 


Limitations 

The XREF program has two limitations on the size of the programs it can handle. 

• An internal limit exists for the number of distinct identifiers allowed. You can change this 
number in the XREF source file and recompile the program. 

• The total number of references is limited by the amount of dynamic storage available. 

The XREF program does not perform a complete syntax analysis of the program, and it may not 
flag all declarations or assignments. 
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Example of XREF Listing 

This example shows the cross-referencing of the program EFACT to produce the output file EFACT.CRF. 
. R XREF 

♦ EFACT/LIST/IIDTH:66 

1 program Efact(output); 

2 { Compute an approximation for E from its Taylor series, 
c 3 The Nth term in the series is 1/(N!). 

c 4 > 

5 

6 var 

7 E, SeriesTerm: real; 

8 N: integer; 

9 

10 begin 

11 { set initial conditions > 

12 E := 1.0; 

13 N := 1; 

14 SeriesTerm : = 1.0; 

15 repeat { loop to approximate E; quit vhen sum stops changing > 

16 E := E + SeriesTerm; 

17 N := N + 1; 

18 SeriesTerm := SeriesTerm / N; 

19 until E = (E + SeriesTerm); 

20 writelnCfith ', N: 1, 1 terms, value of e is 1 , E: 18: 15); 

21 end. 


Cross reference: * indicates definition, = indicates assignment 
-E- 

E 7* 12= 16= 16 19 19 20 

EFACT 1* 

-I- 

INTEGER 8 

-N- 

N 8* 13= 17= 17 18 20 


- 0 - 

OUTPUT 1* 


-R- 

REAL 7 


-S- 

SERIESTERM 7* 14= 16 18= 18 19 

IRITELN 20 



end xref 8 identifiers 24 total references 
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PROCREF, based on a procedural cross-reference program published by Arthur Sale in Pascal News 
(Number 17, March 1980), is designed to help programmers sort through the procedures in medium 
to large Pascal programs. The program has been modified to allow the use of multiple input files 
and {{include directives and to provide “called by* data in the listing. 

PROCREF provides a quick overview of the procedural organization of a program, which is beneficial 
when you’re working with medium to large programs. The PROCREF utility reads the text of a 
Pascal program to produce a compact listing of the procedure headings and an alphabetized list of 
procedures with usage information. PROCREF processes {(include directives in the same way as 
the Pascal-2 compiler, so that all parts of a compilation can be analyzed. 

The procedure listing includes each procedure heading, along with its location in the input file. 
Procedure headings are indented to show lexical level. No attempt is made to fit the procedure 
headings into a limited line width. 

The cross-reference listing places procedures in alphabetical order. For each procedure the listing 
includes: 

• The file and line number where its heading starts. 

• The file and line number where its body starts, unless it is external or is a formal procedure 
parameter and has no body. In such a case, the note external or formal is printed. 

• If the procedure was declared forward or is externally defined, the listing contains the file and 
line number where the procedure heading stub starts. 

• A list of all procedures immediately called by this procedure. These are listed in the order in 
which they occur in the text. A procedure is listed only once, even if it is called more than once. 

• A list of all procedures that call this procedure. Again, the list is in textual order and only one 
reference is shown per procedure. 

Only the first sixteen characters of a procedure name appear in the cross-reference listing. Those 
characters are written exactly as they appear in the program text. 

Using PROCREF 

You invoke PROCREF with the following command: 

. R PROCREF 

* output-tile = input-tiles /width :num 
input-files: 

The Pascal source files being cross-referenced. The input files have a default extension 
of .PAS. Multiple input files, if specified, are separated by commas. Multiple files will 
be concatenated. 

output-file: 

The cross-reference file. The output file has a default extension of .PRF. The output- 
file and the *=’ separator are optional. If they are omitted, an output file with the same name 
as the last input file, and having the default extension, is placed in the default directory.. 

width:n urn 

Specifies the page width for the cross-reference listing, where num is the number of charac¬ 
ters across the page. The default is 80 characters. The width switch is optional and 
may be abbreviated to one letter. 
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Note that the RT-11 system will automatically truncate the name PROCREF to PROCRE. 

Limitations 

The PROCREF program does not do a complete syntax analysis of the program being processed. 
PROCREF will err in one case: If a field identifier in a record has the same name as a procedure, 
and if that field is referenced without a preceding record variable name, as in a with statement, the 
field identifier will be treated as a reference to the procedure. 


Example 

Let's assume that we wish to generate a procedure cross-reference for the following program, 
LVSPOOL.PAS. 

Pascal-2 RT11 SJ V2.1A 5-Aug-83 7:04 PM Site #1-1 Page 1-1 

Oregon Software, 2340 SW Canyon Road, Portland, Oregon 97201, (603) 226-7760 
LVSPOOL/LIST 


1 

2 

3 

4 

5 

6 

7 

8 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 
27 


program LVSpool(input, output); 
procedure ScanLV; external; 

procedure ReadFontInfo(i: integer; j: integer); forward; 


procedure LoadFonts; 
procedure GetByte; 
begin 
end; 


begin 
GetByte; 

ReadFontInfo(l, 2); 


end; 


procedure ReadFontlnfo; 
begin 


LoadFonts; 
end; 


procedure ShowPage; 
begin 


ScanLV; 

end; 


begin 


main program 


ReadFontlnfo(0,1); 
ShowPage; 


end. 


*** No lines with errors detected *** 







Example 


We cross-reference the procedures as follows. 

fi PR QCBEE 

♦LVSP00L=LTSP00L/¥:72. 

The 1:72 requests that the cross-reference listing not exceed 72 characters in width so that the 
result may be printed on a terminal. The result, placed in the file LVSPOOL.PRF, consists of: 

Procedural Crow-Referencer - Tereioa 3.0 
LTSP00L/V:72 

Line Prograe/procedure/function heading 


LTSPOOL.PAS: 

1 prograa LTSpool(input, ontpnt); 

2 procedure ScaaLT; external; 

3 procedure ReadFontInfo(l: integer; J: integer); forvard; 

5 procedure LoadFonta; 

0 procedure GetByte; 

14 procedure ReadFontlnfo; 

19 procedure ShovPage; 


Procedural Croaa-Referencer - Version 3.0 
LTSPOOL/V:72 

Croaa Reference Liating 


GetByte 

Called by 


Head: LTSPOOL.PAS. 0 Body: LTSPOOL.PAS, 7 
LoadFonta 


LoadFonta Head: LTSPOOL.PAS, 5 Body: LTSPOOL.PAS, 9 

Calla GetByte ReadFontlnfo 

Called by ReadFontlnfo 


LTSpool 

Calla 


Head: LTSPOOL.PAS, 1 Body: LTSPOOL.PAS. 24 
ReadFontlnfo ShovPage 


ReadFontlnfo Head: LTSPOOL.PAS, 3 Body: LTSPOOL.PAS. IS 

Forvard, header atub: LTSPOOL.PAS, 14 
Calla LoadFonta 

Called by LoadFonta LTSpool 


ScaaLT 

Called by 


Head: LTSPOOL.PAS. 2 external 
ShovPage 


ShovPage 

Calla 
Called by 


Head: LTSPOOL.PAS. 19 Body: LTSPOOL.PAS. 20 

ScanLT 

LTSpool 
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The Pascal standard implements character strings in two ways: as a sequence of two or more 
characters between single-quote marks (a literal string); or as a packed array of char (a variable 
string). However, the standard does not provide adequate facilities for manipulating character strings 
and only allows assignments of one string to another string and comparisons of two strings of equal 
length. 

Pascal-2’s Dynamic String Package extends the meager string-handling capabilities of standard 
Pascal, providing the ability to perform sophisticated operations on strings of varying lengths. The 
string package, STRING, is a collection of string-processing procedures and functions that allows 
Pascal programs to read and write strings, concatenate two strings, search one string for another, 
insert one string into another and delete one string from another, assign the value of one string to 
another string and other string operations. The string package is written in standard Pascal to take 
advantage of conformant array parameters, which facilitate the passing of variable-length arrays 
(strings), and to provide portability to other Pascal implementations. 

To use the string package, declare string variables as packed arrays of characters with a lower bound 
of 0 and an upper bound equal to the maximum length for that particular string, as shown: 

var 

string-name: packed array [0.. max-fen] of char; 

where string-name is the identifier associated with the string variable and ma x-len is the maximum 
length of the string in bytes. The actual length of the string is stored in element 0. The characters 
making up the string are stored starting at element 1. Max-leu must be greater than 0 and no larger 
than 255. 

The maximum length of a string may be different for each string, depending on the intended use of 
the string. The string package’s use of conformant array parameters makes this possible. Examples: 

var 

laaeString: packed array [0..26] of char; 

Sitelo: packed array [0..7] of char; 

LineOflnput: packed array [0..80] of char; 

As an alternative, these routines also accept parameters of type packed array [1 .. max-Ien] of 
char, where max-Ien is the actual length of the string. Literal strings are of this type. This means 
you may pass a literal string to any of these procedures as long as the formal parameter is not a 
var parameter. 

STRING may be included in program source files in one of two ways: in the program code, place 
the fincludo compiler directive; or on the command line, concatenate STRING.PAS with the rest 
of the source files making up the program (“source concatenation”). We recommend the use of the 
(include directive (e.g., (include 'string';). However, if you concatenate the string package 
with the source file, the command to compile program PROG is: 

R P ASCAL 

♦ STRUG. PROG 

Source concatenation may be used only if the main program does not contain a prograa statement; 
otherwise, compilation errors result. Refer to “Multiple Source Files” in the Programmer Reference 
for more information on the (include directive. 
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The Procedures and Functions 

In the definitions below, string and target represent string variables similar to the previous examples. 
File must be a variable of type text. Start and span, of type Integer, represent character positions 
and character ranges, respectively. Max-len is the upper boundary, or maximum length, of the array. 
Char may be a variable of type char or a literal string of one character. 

The string package contains these procedures and functions: 

Len ( string) 

An integer function, returns the actual length of string. String may be a literal string. 

Clear (string) 

Initializes string to empty. 

ReadString (fi/e, string) 

Reads string from fi/e. The string is terminated when eoln(fi/e) becomes true, and 
a readln(£/e) is performed. Overflow results in truncation to max-len characters. 

VriteString (fi/e , string) 

Writes string to fi/e. This procedure does not accept literal strings as parameters. 
Use vriteln to terminate a written string manually. 

Concatenate (target, string) 

Appends string to target. The resulting value is target. String may be a literal string. 
Overflow results in truncation to max-len characters. 

Search (string, target, start) 

Searches string for the first occurrence of target to the right of position start (characters 
are numbered beginning with 1). The Search function returns the position of the 
first character in the matching substring, or the value zero if target does not ap¬ 
pear in string. String and target may be literal strings. 

Insert (target, string, start) 

Inserts string into target at position start. Characters are shifted to the right as 
necessary. Overflow produces a truncated target of max-len characters. The inser¬ 
tion is skipped if the start position causes a non-contiguous string. String may be 
a literal string. 

Assign (target, string) 

Assigns string to target. This procedure is especially useful for assigning a literal 
string to a variable string (target). To assign one character to a variable string, 
use the Asschar procedure, below. 

Asschar (target, char) 

Assigns char to target. Char may be a literal character or a variable name. This 
procedure is more efficient than procedure Assign for the creation of one-character 
strings. (With Assign, a one-character string must first be created as input to Assign, 
which then assigns the character to a variable string.) 

Equal (target, string) 

Determines whether target is element-for-element identical to string. This boolean 
function returns a true value if the two strings are equal, false if the two strings 
are different. Target and string may be literal strings. 

The start and span parameters in the Deistring and Substring procedures define a substring 
beginning at position start (between characters start-1 and start) with a length of abs(span). If 
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Example 


procedure GetDirective(I: integer); 
var 

Ch: char; 

begin { GetDirective > 

Clear (Directive) ; --- defined in STRING 

while I <= Len(Line) do begin { not end of line yet > 

Ch := Line[I]; I := I + 1; 

if Ch in Letters then begin { get next char of directive > 

Directive[0] := succ(Directive[0]); 

Directive[Len(Directive)] := Ch 
end 

else I := Len(Line) + 1; 
end; 

DirectiveFound := Len(Directive) > 0 
end; { end GetDirective > 

begin { DirectiveList > 
write('PROSE FILE: '); 
readln(Name); 

reset(Prosefile, Name, 1 .prs 1 ); 
rewrite(Directivefile, 1 .dtv 1 , Name); 

Assignchar (Escape , 1 . 1 ) ; defined in STRING 

Linenum := 0; 

Letters := ['A'..'Z‘, , a , .. , z 1 ]; { Any others end directive > 

while not eof(Prosefile) do begin 

Readstring (Prosef ile, Line) ; -—- defined in STRING 

Linenum := Linenum + 1; 

if Line[1] = Escape[1] then begin { first character is an escape > 
Index := 0; NoneYet := true; 

repeat { find all occurrences of escape characters > 

Index := search (Line, Escape, Index + 1); — defined in STRING 

if Index <> 0 then begin 

GetDirective(Index +1); < get the next directive > 

if DirectiveFound then begin 

Assign (Out line. Escape) ; - defined in STRING 

Concatenate (Outline, Directive) ; - defined in STRING 

if NoneYet then begin 

write(Directivefile, 1 Line •. Linenum: 4.* '); 

NoneYet := false 
end 

else write(Directivefile, 1 '); 

WriteString(Directivef ile, Outline); — defined in STRING 

writeln(Directivefile); 
end; 

end; 

until Index =0; 
end; 

end; 

end. { DirectiveList > 

For this illustration, PDLIST reads the PROSE input file presented in Appendix A of “PROSE: A 
Text Formatter,” Example 2, later in this guide. The name of the input file is PEXAM2.PRS. To 
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see what the input looks like, refer to the aforementioned example in the PROSE section. 

Run PDLIST using these commands: 

. R PASCAL 
♦ PDLIST 

. LINK PDLIST,SY:PASCAL 

. RUN PDLIST 
PROSE FILE: PEXAM2 

Output — the list of directives used in the file — is written to PEXAM2.DTV, which looks like this: 


Line 

1 

.COMMENT 

Line 

2 

.INPUT 

Line 

3 

.OPTION 

Line 

4 

.FORM 

Line 

5 

.MARGIN 

Line 

6 

.PARAGRAPH 

Line 

21 

.OPT 

Line 

22 

.MAR 

Line 

23 

.PARAGRAPH 

Line 

28 

.OPT 



.MAR 



.PAR 
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Although most programs can be written within the Pascal-2 language, applications involving inter¬ 
face to the operating system require the use of MACRO-11 assembly language code. A set of macros 
provided with the Pascal-2 system makes this interface easy. You can code a set of macro calls 
that look much like a Pascal procedure declaration, and the PASMAC macro package will assign 
addresses to the parameters and generate procedure entry and exit code. 


Design of MACRO-11 Procedures 

Follow these general rules in deciding what to put in a MACRO-11 procedure: 

• Do the absolute minimum in MACRO-11. If you must use MACRO-11 code to use a system 
service, process the result in Pascal-2 code. (This is not always possible, since some operating 
systems require very low-level manipulations.) 

• Isolate a common function and make the procedure handle the most general case of that 
function. 

• Pass all data to and from the procedure as parameters. Global references from MACRO-11 are 
not recommended for these reasons: the address is hard to find; if the Pascal program changes, 
the MACRO program will have to be changed; and global references cannot be checked for type 
compatibility. This guide does not describe ways to make global references. 

Once you have decided on the contents of the procedure, define the calling sequence as a Pascal 
external procedure. Then write a functional description of the procedure. Then actually write the 
procedure. These documents will be your implementation guide. 

When you have the external definition, use the PASMAC macro package described below to define 
parameters and local variables. As long as the stack is not changed within the procedure, these 
macros can access parameters or local variables directly. For this reason, you should probably store 
local temporary values in the local variables rather than pushing them on the stack. If thoroughly 
familiar with writing MACRO-11 code, you can use the stack, but make sure you understand the 
Pascal-2 run-time structure, described in the Programmer’s Guide. 
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The PASMAC Macro Package 


The PASMAC macro package is provided to simplify the writing of MACRO-11 procedures to 
interface with Pascal-2. Using this package, you can declare procedures, parameters, and variables, 
and you can easily refer to these items within the procedure. 

The package consists of the following macros: 


Name 

Arguments 

Function 

proc 

procname 

Begin the declaration for the procedure procname . 

f unc 

funename 

Begin the declaration for the function function . The 


result 

returned value will be that assigned to result 7 of type 


restype 

restype. 

param 

parmname 

parmtype 

Declare a parameter named parmname of type parmtype. 

var 

varname 

vartype 

Declare a local variable named varname of type vartype. 

save 

<regO, ... t regn> 

Specify general registers to save on procedure entry. 

rsave 

<acO, ... ,a cn> 

Specify floating accumulators to save on procedure entry. 

begin 


Begin the actual procedure code. This macro generates 
code to push the variables on the stack and to save 
registers. 

endpr 


End the code for this procedure, restore registers, pop 
variables and parameters from the stack, and return to 


the calling location. 

The following example demonstrates how these macros may be used in a procedure definition. Note 
the correspondence between the Pascal-2 code and the MACRO-11 code. 

Pascal-2 procedure definition: 

procedure ExamplClnpl: integer; { first value parameter } 

Inp2: real; { second value parameter > 

var Qutp: integer { variable parameter »; 


var 

Varl: integer; 

Arrl: array [1..3] of integer; 
begin 


end; 


{ first local variable > 

{ second local var > 

{ begin body of procedure > 

--procedure code 

{ end of procedure > 
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The corresponding MACRO-11 code: 


proc 

exampl 

par am 

inpl,integer 

par am 

inp2,real 

par am 

outp,address 

var 

varl,integer; 

var 

arrl,3*integer 

save 

<rO,rl> 

rsavo 

<acO,acl> 

begin 


endpr 



Using PASMAC 


; declare the procedure 
; first value parameter 
; second value parameter 
; variable parameter 

; first local variable 
; second local variable 

; registers being used 
; floating accum being used 

; begin body of code 

-— procedure code 

; reset everything and return 


The macros described in the following sections are included in the file PASMAC.MAC, which also 
includes definitions of standard data types. It is assumed that this file will be assembled as a header 
to any MACRO-11 code. This would normally be done with a command line similar to: 

. R MACRO 

♦ EXTPRO.EXTPR0=SY:PASMAC,EXTPRO 


The result of this assembly is an object file (.OBJ) that is linked in the same way as any other 
external module. 

MACRO-11 modules assemble with the PASMAC package are referenced from Pascal via the ex¬ 
ternal directive instead of the nonpascal directive, because PASMAC simulates the Pascal calling 
sequence. (MACRO-11 routines assembled without the PASMAC package can be referenced via the 
nonpascal directive.) For example: 

procedure ExtProc(Parml: integer); 
external; 


For details, see “External Modules” in the Programmer’s Guide. 

The example command line above also generates a listing file (.LST). Listing of the PASMAC file is 
disabled with a .NLIST directive at the start of the file. A compensating .LIST directive is placed 
at the end of the file, so a program listing is not affected. Defining the tag $LIST anywhere in your 
code will enable listing of the PASMAC file. 

The macros depend on the existence of a uniform radix throughout the declaration of a single 
procedure. This radix may be octal or decimal, but it must not be changed within a procedure 
declaration. Also, the macros use labels of the form ft$xxx and macros of the form tPxxx for storing 
state data. Avoid such forms in your own code. 
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Procedure Definition Macros 


The PASMAC procedure definition macros must be used in the order: 


Macro 

proc/func 
par am 
var 

save/rsave 

begin 


endpr 


Usage 

Exactly one of these is required 
As many as required (or none) 
As many as required (or none) 
Either or both as needed 
Required 

User code 
Required 


A MACRO-11 error is detected if the macro calls are not made in the required order. 


Above references to parameter and variable “types” assume that “type” identifiers are equivalent 
to the length of a value of that type. For example, the identifier integer has the value of 2, the 
identifier real has the value of 4, and a disk buffer may have the value of 512. The PASMAC package 
defines some standard types. See “Type Definitions” below. 

Parameter, variable and function result names are set to offsets relative to the value of the stack 
pointer at the end of the begin macro. This takes into account local variables allocated on the 
stack, plus the space used for register saving. You must take into account any additional values you 
pushonto the stack. 

Examples: 

param par ami, integer ; defines par ami 

mov paraml (sp) , rO ; use paraml 


The ‘Proc* Macro 


The proc macro, used to begin the definition of a procedure, specifies the name to be used and 
initializes the symbols that store data about the procedure. This macro must be the first macro used 
in a procedure declaration. 

The calling sequence is: 

proc procname[, check=l] 

where 


procname 

is the name to be used to call the procedure. Only the first six characters of this 
name are significant. 


check is an optional parameter specifying stack overflow checking. A non-zero value (default) 
requests a stack overflow check. This check is free (and always done) if more than three 
registers are saved, and costs two words in the procedure entry otherwise. The time 
for the check is very small, so disabling it is not recommended. 


Examples: 


proc p,check=0 

or: 

proc p,0 
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Begins the declaration of a procedure with the external name p and no stack overflow checking, 
proc save time 

Begins the declaration of a procedure with the external name saYeti and stack checking enabled. 

The ‘Func* Macro 


The func macro, similar in function to the proc macro, also allows you to specify a name and type 
for the returned value. In Pascal, the returned value is specified by assignment to the function name. 
In MACRO-11, this assignment is not possible, since the function name is used for the procedure 
entry and cannot also point to the appropriate place on the stack. Any value assigned to the result 
name defined in the func macro at exit from the function is returned as the function value. 

The calling sequence is: 

func funename , resname , restype[, check=l] 

where 


funename 

is the name to be used to call the function. Only the first six characters are significant. 

resname is the name to be used to reference the returned value. Any value assigned to this 
location during execution is returned to the calling program upon exit from the 
procedure. 

restype is the length of the result value. This is not used in the current implementation of the 
macros, but is included for documentation and possible future use. 

check is an optional parameter that enables stack checking if non-zero. See the description 
under the proc macro. 

Example: 

func curtime,tval,real 

Begins the declaration of a function with the external name curtim and stack overflow checking 
enabled. The result location will be named tval, of type real. Here real is assumed to hare the 
value 4, which is the length of a single-precision real value. 


The ‘Parana’ Macro 

The param macro specifies parameters to the current procedure or function. Each parameter has 
one param macro, in the order declared in the Pascal procedure declaration. In the Pascal—2 calling 
sequence, parameters are pushed onto the stack in the order in which they are declared, so the first 
parameter is at a higher address than the last parameter. Value parameters have the actual value 
pushed, and variable parameters have the address of the variable pushed. When these parameters 
are declared, the parameter name is set equal to the offset of that parameter relative to the stack 
pointer (sp) after the begin macro has been called. This value may be used to access the parameter 
location relative to the stack pointer. 

The calling sequence is: 

param paramname, paramtype 
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where 

paramname 

is the name to be used for accessing the parameter. Within the body of the procedure, 
if the stack pointer (sp) has not changed since the begin macro, value parameters 
can be referred to by paramnaizie(sp), and variable parameters can be referred to 
as Qparamname(sp). 

paramtype 

is the data type used to determine the space on the stack used by this parameter. 

Examples: 

param input,integer ; input: integer 

param result,address ; var result: integer 

These macros define two parameters. The first is a value parameter with the name input of type 
integer and is referred to in the body of the procedure as input (sp). The second is a variable 
parameter with the name result of type integer. Note that the type is defined only in the comment; 
the actual value pushed on the stack is of type address. Within the body of the procedure this is 
Oresult(sp). 


The ‘Var’ Macro 

The var macro, similar to the param macro, defines a local variable to be allocated on the stack 
upon procedure entry. The space for these variables is allocated automatically by the begin macro, 
but is not initialized. Such variables are referenced relative to the stack pointer (sp). 


The calling sequence is: 


var varname, vartype 

where 

varname is the name to be used for accessing the variable. Within the body of the procedure, if 
the stack pointer (sp) has not been modified since the begin macro, variables can be 
referred to by varaame(sp). 

vartype is the data type used to determine the space to be allocated for this variable. 


Example: 

var temp,integer ; temp: integer; 

var name,10*char ; name: array [1..10] o 1 char; 

The example defines two local variables. The space for these variables will be pushed onto the stack 
by the begin macro. The variable temp has two bytes allocated and is referred to as temp(sp). The 
variable name has ten bytes allocated and is referred to as name(sp). 

The ‘Save* Macro 


The save macro specifies the general registers to be saved on procedure entry. The Pascal-2 calling 
conventions require a procedure to save and restore all registers used within a procedure, so any 
registers altered within the procedure should be listed here. If more than three registers are to be 
saved, a routine from the Pascal support library is used to save the registers. The stack pointer and 
program counter (sp and pc) cannot be saved. 

The calling sequence is: 

save <regl , ..., regn> 
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where <regl t .... regn> is a list of registers to be saved, enclosed in angle brackets (<>) and 
separated by commas. These registers will be saved on entry and restored on exit. The registers sp 
and pc cannot be saved, as they are modified by the action of saving them. 

Examples: 

save <rO,rl> 

Save registers BO and R1 and restore them on exit. The code generated uses explicit xbov instructions 
to do this. 

save <r0.rl,r2,r3,r4,r6> 

Save and restore all available registers. Support routines will be used. 


The ‘Rsave’ Macro 

The rsave macro is useful only for machines with the Floating Point Processor (FPP) hardware 
option and serves the same function as save except for the floating-point accumulators. You are re¬ 
quired to specify the FPP mode, either single or double (default is single). Since the accumulators AC4 
and ACS cannot be moved directly to memory, they may not be used unless one of the accumulators 
ACO to AC3 is also used. Of course, you cannot get data into AC4 or ACS without using one of the 
lower accumulators, so you should not have any problems meeting this requirement. 

The calling sequence is: 

rsave <a ccuml, .... accumn>[, double=0] 

where 

<a ccuml, .... 2LCcumn> 

is a list of accumulators to be saved, enclosed in angle brackets (<>) and separated 
by commas. These registers will be saved on procedure entry and restored on procedure 
exit. 

double is an optional parameter that specifies the saving of two-word accumulators. If set to 
1, specifies that the FPP is in double mode. The default is zero. The setting does not 
affect the setting of the FPP; it simply allows the correct computation of the space 
required for the registers. 

Examples: 

rsave <ac0,ac4> 

Save accumulators ACO and AC4 and assume that the FPP is in single mode. 

rsave <acO>,double=l 

or: 

rsave acO.l 

Save accumulator ACO and assume that the FPP is in double mode. 

The ‘Begin’ Macro 

The begin macro marks the start of the procedure body. This and the endpr macro are the only 
ones to actually generate code. When the begin macro is assembled, all of the data saved up by 
the previous macros is used to generate procedure entry code and define all of the parameter and 
variable addresses. 

The calling sequence is: 

begin 
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The ‘Endpr* Macro 

The endpr macro marks the end of the procedure body. Only one endpr is allowed in each procedure. 
When the endpr is assembled, registers are restored, the variables and arguments are popped off the 
stack, and control is returned to the calling procedure. The endpr macro is designed to generate 
good code for popping the stack and returning. 

The calling sequence is: 

endpr 


,;T- 
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Type Definitions 

In addition to the procedure definition macros described above, the PASMAC package defines some 
standard “types” and provides a set of three macros to simplify the definition of data structures. 
Each type is represented by its length in bytes. 

The predefined types are: 

Type Length 

char 1 

boolean 1 

scalar 1 

integer 2 

pointer 2 

address 2 

real 4 

double 8 

procpar 4 

The type procpar is actually a record definition having two fields. This type is explained below. 
The structure definition package consists of three macros: 


Name 

Argument 

Function 

record 

typename 

Begins the definition of a record type typename. The sym¬ 
bol typename will be set to the length of the record at 
the end of the definition. If the data type is procpar, the 
record is a procedure being passed as a parameter to a 
MACRO-11 routine. 

field 

name 

size 

Defines a field in the record. The fields are allocated in 
ascending order, and any field with a length greater than 
1 is allocated on a word boundary. Fields so defined are 
set equal to the offset of the field relative to the beginning 
of the structure. 

endrec 


Ends the definition of a record and assigns the total length 
to the typename given in the record macro. 


For example, consider the following Pascal record definition: 

prec = record 
Intfl: integer; 

Inti2: integer; 

Boolfl: boolean; 

Realfl: real; 
end; 


The equivalent code using the structure-definition macros is: 


record 

prec 

field 

intfl, integer 

field 

intf2,integer 

field 

boolfl.boolean 

field 

realfl,real 

endrec 



prec = record 
intfl: integer; 
inti2: integer; 
boolfl: boolean; 
realfl: real; 
end; 
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Later in the procedure, where the definition above occurs, we find: 

var local,prec ; local: prec 

And we would refer to field intf 2, for example, as 
mov local+intf2(sp) , rO 

The type procpar is used in rare cases when you are passing a procedure as a parameter to a 
MACRO-11 routine. The definition is: 

record procpar 

field pp.proc,address ; address of the procedure 

field pp.stat,address ; address of the enclosing static link 

endrec 
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Example 

This example shows the coding of a MACRO-11 procedure for use with Pascal-2. The procedure 
chosen for the example is not one that would normally be coded in MACRO-11, but most such 
procedures are extremely dependent on the operating system. In fact, we begin with a version of the 
algorithm as it is coded in Pascal-2: 

{$nomain> 

procedure CountOnes(N: Integer; 

var Ones: integer; 
var First: integer 

external; 

{ This is a procedure that counts the “one" bits in an integer and 
returns the number of ones in "Ones" and the highest bit found 
in "First". If no bits are set, "First" receives "-1". 

The procedure uses an extension of Pascal"*2 that allows the 
signed number "N" to be treated as an unsigned number "TN“. 

> 

procedure CountOnes; 
var 

TN: 0..65535; 

Bits: 0..16; 

begin 

First := -1; 

Ones := 0; 

Bits := 0; 

TN := N; 
while TN <> 0 do begin 
if odd(TN) then begin 
Ones := Ones + 1; 

First := Bits; 
end; 

Bits := Bits + 1; 

TN := TN div 2; 
end; 

end; 

This simple procedure counts the number of bits set in an integer, checking whether the lowest bit is 
set, incrementing a counter, and terminating when there are no more bits set. The use of unsigned 
integers (TN, in the range 0..65535), avoids the shifting of the sign bit into the lower-order bits. 
(Unsigned integers are discussed in the Programmer’s Guide and in the Language Specification.) 
This procedure (and many others that are often coded in low-level code) can be coded as a Pascal-2 
procedure. But in many ways this procedure is typical of the sort of procedure you may code in 
MACRO-11: 

• It performs a single function with simple internal logic. 

• It is a generally useful form of the function, rather than a special use. 

• It makes no reference to global variables. All data is passed as parameters. 

The first example gives the most direct translation into MACRO-11, with all references to variables 
made directly to memory. It is quite possible to do the entire function in registers, with some saving 


{ local unsigned value of N > 
{ bit count > 


{ number to count bits in } 
{ number of "one" bits } 

{ highest "one" bit »; 
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in code and execution time, but for the sake of the example we will not do this. We change the 
algorithm slightly to make use of the state of the condition code at the end of the loop. The use of 
a conditional branch at this point shortens execution time slightly at no cost in code size. 

.title count 

; This is a sample procedure that counts the number of bits 
; set to one in a word "n“ and also sets the variable "first” 

; to the bit number of the highest bit set. 

; This is used strictly as an example; some values that would 
; normally be kept in registers are being kept in local variables 
; or handled directly in memory for demonstration purposes. 


1 $: 


2 $: 


10 $: 


proc 

countones 

procedure countones( 

par am 

n,integer 

n: integer; 

par am 

ones ( address 

var ones: integer; 

par am 

first,address 

var first: integer); 


i 

; var 

var 

bits,integer 

bits: integer; bit counter 

begin 

i 

; begin 

mov 

#-l,0first(sp) 

; first := -1; 

clr 

Qones(sp) 

; ones := 0; 

clr 

bits(sp) 

; bits := 0; 

tst 

n(sp) 

if n <> 0 then 

beq 

10$ 

repeat 

bit 

#l,n(sp) 


beq 

2$ 

if odd(n) then begin 

inc 

Qones(sp) 

ones : = ones+1; 

mov 

bits(sp),0first(sp) 



first := bits; 
end; 

inc 

bits(sp) 

bits := bits + 1; 

clc 



ror 

n(sp) 

n := n div 2; 

bne 

1$ 

until rO = 0; 

endpr 



. end 




This procedure illustrates the use of parameters, local variables, and the begin and endpr macros. 
The local variable to hold n is not needed as there is no distinction made between signed and unsigned 
integers at the MACRO-11 level. The equivalent Pascal-2 code in the comments should make the 
MACRO code easy to follow. 

In actual practice, local variables would be kept in registers, and the save and restore macros 
would be used to save and restore the registers used. The following version is an example of this 
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kind of code. 

.title count 


This simple procedure counts the number of bits 

set to one in a vord "n" and also sets the variable "first" 

to the bit number of the highest bit set. 

Functionally, this is the same procedure as "examp", except that 
it places local variables in registers whenever possible. 


1 $: 


2 $: 


10 $: 


proc 

countones 

par am 

n,integer 

par am 

ones,address 

par am 

first,address 

save 

<r0,rl,r2.r3> 

begin 

mov 

n(sp) ,r0 

mov 

#-l,rl 

clr 

r2 

clr 

r3 

tst 

rO 

beq 

10$ 

bit 

#l,r0 

beq 

2$ 

inc 

r2 

mov 

r3,rl 

inc 

clc 

r3 

ror 

rO 

bne 

1$ 

mov 

rl,0first(sp) 

mov 

endpr 

.end 

r2,Qones(sp) 


procedure countones( 
n: integer; 
var ones: integer; 
var first: integer); 


r0 := n; 
rl := -1; first 
r2 := 0; ones 
r3 := 0; bits 

if r0 <> 0 then 

repeat 

if odd(rO) then begin 
r2 := r2+l; 
rl := r3; 
end; 

r3 := r3 + 1; 

rO := r0 shift 1; 
until rO = 0; 

first := rl; 
ones := r2; 


In the Pascal program that invokes CountOnes, the following reference is made: 

procedure CountOnes(N: integer; 

var Ones: integer; 
var First: integer); 

external; 


Example 
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Placing PASMAC into the System Macro Library 

If you often write Pascal programs that invoke MACRO- 11 subroutines written using the PASMAC 
macro package, you might find it desirable to add the PASMAC package to your system macro 
library. This allows MACRO- 11 programs to use PASMAC via the .MCALL assembler directive rather 
than by specifying PASMAC.MAC as a separate input file in the command line. 

When you assemble a MACRO-11 subroutine, the assembler searches the system macro library 
(SY:SYSMAC.SML) to define macros requested with the .MCALL directive. The system macro library 
normally contains definitions of macros that call system services. You can easily add your own macro 
definitions to this library. 

To add PASMAC to the system macro library, perform these steps: 


1. Make a backup copy of your system macro library in case something goes wrong. 

2. Using a text editor, create a file called P.MAC, which encloses PASMAC.MAC with a macro 
definition, as shown below. The definition creates a macro called PASMAC, which contains the 
entire contents of the file PASMAC.MAC. The macro definition redefines the macro PASMAC 
to be a null macro. This saves space and time in the assembler. The macro definition must be 
in upper case. 

.MACRO PASMAC 


: -—-contents of PASMAC.MAC 

.MACRO PASMAC 
.ENDM 


.ENDM PASMAC 

We offer two ways to create P.MAC. The first way is to create the skeleton macro, then insert 
the contents of PASMAC.MAC at the location shown above. The other possibility is to first 
copy PASMAC.MAC to P.MAC and then edit P.MAC, placing the skeleton macro directives 
around the contents of PASMAC.MAC. 

3. Copy SYSMAC.SML to some other file, say SYSMAC.XXX. 

4. Run the librarian to add the contents of P.MAC to SYSMAC.XXX. This produces SYSMAC.SML, 
the new system macro library. 

. R LIBR 

♦ SYSMAC.SML/M=SYSMAC.XXX.P.MAC 


PASMAC.MAC is now a part of the system macro library. You can now use the .MCALL directive to 
define the PASMAC macros in your MACRO routines. This is illustrated below. The routine simply 
clears registers RO and Rl. 


.title 

test 


.mcall 

pasmac 

; Read the PASMAC macro 

pasmac 


; Define PASMAC macro 

proc 

test 

; Sample procedure 

par am 

foo,integer 


save 

<rO,rl> 


begin 



clr 

rO 


clr 

rl 


endpr 



. end 
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Placing PASMAC Into the System Macro Library 


Now you can assemble the routine without specifying the PASMAC.MAC source file on the 11ACR0 
command line. 

. MACRO TEST=TEST 
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Computerized text-processing tools such as text editors and formatters can ease the tedious prepara¬ 
tion and editing of computer-oriented documentation. Instead of cutting, pasting, and retyping hard 
copy, you instruct the computer to insert changes, reformat and number pages, then reprint the 
document. PROSE, a text-formatting utility program, allows you to print any document in a variety 
of formats. 

This guide describes the operation of PROSE, providing an overview of text-formatting procedures 
for PROSE and a detailed explanation of PROSE directives. The first-time user of PROSE can 
read this guide from beginning to end, using it as a tutorial while producing a first document. The 
more experienced reader may use it as a reference source. As an aid to both, this guide groups 
PROSE directives by function into four sections: controlling input, establishing format, indexing, 
and printing. The order of the directives in the guide reflects the order in which these directives 
might be applied to a text. The reader should have some basic knowledge of a text editor. 

PROSE requires a small number of easily learned commands. Unlike some text-formatting programs, 
which use macro commands, variables, and other features usually associated with programming 
languages, PROSE does not overwhelm the user with complicated syntax. The text stands out, not 
the directives. This simplicity allows you to produce high-quality text with a minimum of effort. 

Like many text formatters, PROSE will format text in pages, filling and justifying lines, placing titles 
and page numbers as needed. The following table shows some common features of text formatters 
that PROSE does and does not have. 


Prose Can 


m. And Cannot 


Underline 
Hyphenate words 
Convert upper-case input 
to mixed-case output 
Produce a sorted index 
Print selected pages 


Control photo-typesetting machines 
Do graphics 

Produce multi-column text 

Store text and retrieve it later 
Use tabs 


PROSE may or may not be the tool for a given application. 
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PROSE Basics 

The basic units of any texMormatting system are the word, the line, and the paragraph. In PROSE, 
a word is defined as any non-blank string of characters, with a blank on either side. For the purposes 
of formatting, a punctuation character is part of the word next to it. A line consists of the number 
of words that PROSE can fill between margins. PROSE places as many words as possible into each 
output line, adding blanks to justify the lines to left and right margins. 

Text formatting is largely filling and justifying, a process illustrated by the following example.* 
Input to PROSE: 

Eddie vent to the ground floor cafeteria and got a sandwich 
and container of coffee, then went back to his office to work on 
the water bill survey. No one else was there; the others were still 
out on their regular lunch hour. 

Why not? he asked himself. It took only ten minutes from start to 
finish: eight to find the code, one to decide how to do it, and one 
more to type the orders into the computer console. When he finished, 
the screen told him that the violation number had been removed. 

A few minutes later his office door opened. It was his boss. He was 
back ten minutes early from his lunch hour. 

"You're here," the boss said. 

"That's right," Eddie said. 

"Good," the boss said, leaving without bothering to close the 
door. 

Output from PROSE: 

Eddie went to the ground floor cafeteria and got a sandwich and 
container of coffee, then went back to his office to work on the water 
bill survey. No one else was there; the others were still out on 
their regular lunch hour. 

Why not? he asked himself. It took only ten minutes from start to 
finish: eight to find the code, one to decide how to do it, and one 
more to type the orders into the computer console. When he finished, 
the screen told him that the violation number had been removed. 

A few minutes later his office door opened. It was his boss. He 
was back ten minutes early from his lunch hour. 

"You're here," the boss said. 

"That's right," Eddie said. 

"Good," the boss said, leaving without bothering to close the door. 

When the user gives no special instructions, called directives, PROSE operates in the default 
mode as shown in the example above. In the default mode, PROSE automatically fills and justifies 
output lines, formatting the output into pages. Directives instruct PROSE to do anything more 
sophisticated. If the user doesn’t enter certain directives, PROSE supplies their default forms. 


* Text examples in this guide have been excerpted from The Programmer by Bruce Jackson. 
Copyright © 1979 by Bruce Jackson. Reprinted by permission of Doubleday & Company, Inc. 
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Structure of Directive Lines 

In general, a directive line has three components: the escape character, the directive name, and the 
parameter for its application. Most PROSE directive lines take one of three forms: 

. directive name 
. directive name integer 
.directive name ( parameter ) 

The directive escape character is placed in the first column of an input line to indicate that at 
least one directive follows. The period (.) is the default escape character because it seems unlikely 
that anyone would want to type a period in the first column of a line of text. The default can be 
changed with the INPUT directive (see “Controlling Input to PROSE”). 

After the escape character comes the name of the directive that PROSE is to execute. The directive 
name can be abbreviated to three letters (in fact, PROSE only examines the first three). Examples 
in this guide show directives typed in upper case, but PROSE accepts both cases. 

The directive name may or may not be followed by a parameter . The BREAK directive, for example, 
doesn’t require a parameter. If a necessary parameter is omitted, PROSE supplies a default value 
for that parameter. The default values that PROSE uses are listed in a table of options under each 
directive. 

A parameter can be one of three types: 

• Text on the remainder of the directive line. 

• An integer. 

• Any specific options enclosed in parentheses, consisting of other directive names, integers, or 
keywords defined by the directive itself. 

In text-processing systems such as PROSE, a keyword (also called a descriptor) categorizes or indexes 
information. Many PROSE directives use special letters or characters to express the options assigned, 
as do the INPUT or FORM directives. In directives such as RESET ( MARGIN ), the keyword is the name 
of the directive to be changed. The summary directive table in Appendix B indicates the parameter 
type that each directive may take. 

Numeric values used as a parameter or part of a keyword may be either an explicit positive integer 
or a relative value. A relative value, specified by a plus or minus sign before the integer, indicates 
that the old value should be increased or decreased by the amount of the integer. For example, if the 
left margin is set to 10 and the right margin to 70, you could use a relative values in the directive 

.MARGIN( L+5 R-5 ) 

to squeeze the margins together by 5 characters on each side. 


Placement of Directives 

Directive lines are usually separated from lines of text (see the following sample file). Several 
directives can be typed on the same line, provided that they are separated by the directive escape 
character, as follows. 

.BREAK.SKIP 2.MARGIN( L5 R65 ) 

Some directives take the remainder of the line as their parameter, so no other directives can follow 
these (e.g., COMMENT directive). The following sample shows the placement of PROSE commands in 
an input file. 
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Input to PROSE: 

.COMMENT This example makes very primitive use of directives, 

.COMMENT but it will produce exemplary text. 

.MARGIN( L10 R60) 

.INDENT 2 

Eddie ordered that the tax roll and Yellow Pages tapes be returned 
to storage. A few seconds later the video screen told him they had 
been returned to their appropriate storage locations. 

.BREAK.INDENT 2 

Eddie smiled at the screen. He loved the computers. They would do 
exactly what you told them to do and they would never lie to you. 

Two inhuman characteristics. People who complained about the i nhum anity 
of computers were right. They didn't know how to care or betray. 


.BREAK.INDENT 2 

The next operation was more complicated. He had prepared for 
it some time before, and the preparation had required many 
separate inquiries. 


Output from PROSE: 

Eddie ordered that the tax roll and Yellow Pages 
tapes be returned to storage. A few seconds later 
the video screen told him they had been returned 
to their appropriate storage locations. 

Eddie smiled at the screen. He loved the 
computers. They would do exactly what you told 
them to do and they would never lie to you. Two 
inhuman characteristics. People who complained 
about the inhumanity of computers were right. 
They didn't know how to care or betray. 

The next operation was more complicated. He had 
prepared for it some time before, and the prepara¬ 
tion had required many separate inquiries. 


For more sophisticated examples, see “Appendix A: Examples of PROSE Directives in Text. 


A long directive may extend beyond one line. A continued line is indicated by a continuation 
character, a plus sign *+’ placed in column one. The following example shows suggested placement 
of the continuation character: 


.FORMC [ III L58 // #73 'PAGE 1 p III ] 

+ [ III L58 // 'PAGE' p III ] ) 

Generally, directives are placed at the beginning of the input file or at the point in the text where the 
directive takes effect. Most directives either control the functions of PROSE or set general format 
guidelines for the document. These are placed at the beginning of the text and their operations are 
applied throughout, unless temporary changes are made. The FORM directive, for example, establishes 
page format for the rest of the text, but the number of lines per page can be adjusted by an option 
of the PARAGRAPH directive. Directives that apply only to a particular line, such as INDENT, BREAK, 
and COMMENT in the sample above, are placed wherever necessary throughout the text. 
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Running the PROSE Program 

No actual formatting takes place until the input file, containing text and directive lines, is submitted 
to PROSE for processing. You create the input file with your system’s text editor. PROSE places 
the formatted text in an output file for submission to a printer or for display on a terminal screen. 

To format the input file, invoke PROSE as shown: 

. R PROSE 

* output-61e = input-file 
input-file: 

The PROSE source file(s). Multiple input files are read and concatenated from left 
to right. The default extension for input files is .PRS. 

output-file: 

The formatted PROSE file. If the output file and the *=’ separator are omitted from 
the command line, the output file will take the name of the last input file and the 
default extension .DOC. Default output files are placed in the default directory. 

The output file may then be printed. The formatting and printing operations may be merged by 
means of header files. 


Header Files 

Certain directives nearly always appear at the head of any input file. If all of your documents 
use these directives in the same form, you can set up a header file rather than type them in each 
document’s input file. Header files also provide you with an easy way to choose among various forms 
or output devices. 

As a general practice, we recommend that you set up each PROSE text without OUTPUT or FORM 
directives. Instead, keep these directives in another file that you will use as the first input file, or 
“header file.” For example, you may wish to create a header file for output to a video terminal and 
another for output to the line printer. 

If your header files are stored on the system device, you would use this command to prepare the 
document for the terminal (assuming the header file is named VT100.PRS): 

. R PROSE 

♦ DOCNAM = SY:VT100,DQCNAM 

and this command to prepare the document for the line printer (assuming the header file is named 
PRINTR.PRS): 

. R PROSE 

♦ DOCNAM = SY:PRINTR,DOCNAM 

PROSE prints the output file according to directives in the header file. See “Page Format” and 
“Specifying Output Devices” for the functions of the individual directives included in the header 
file. 
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Controlling Input to PROSE 

The directives in this section control the input to the PROSE program. Generally, they are placed 
at the beginning of the input file for a document or in a header file to be used for all documents. 
You can set and change them as needed throughout the text. 

INPUT Directive 

The INPUT directive tells PROSE how to interpret certain control characters in the input file and 
sets the maximum length for input lines. 

The following table summarizes the options for its parameter. 


Key Letter 

Meaning 

Type 

Default 

B 

Explicit blank character 

character 

nul 

v H 

Hyphenation character 

character 

nul 

C 

Case-shift character 

character 

nul 

u 

Underline character 

character 

nul 

D 

Directive escape character 

character 

• 

V 

Input width 

number 

150 

K 

Keep 

number 

next 


The options, which can be given in any order, consist of a key letter followed by a value. Unless 
the user specifies both the key letter and a value, the default value is assigned when PROSE begins 
processing. A value in the parameter changes only when a new value is given. No INPUT option uses 
relative values. 

B: The explicit blank character indicates a blank that PROSE should treat as if it were 

a character. With the cross-hatch 4 #’ specified as the explicit blank, the following example 
shows how two words separated by an explicit blank will never be split from one line to 
the next. PROSE will never fill blanks between the words to justify a line. 

.INPUT( B# ) 

...someone like the imaginary Dr.#Conrad and... 

H: The hyphenation character defines hyphenation points within words. Sometimes a long 

word will cause many blanks to be inserted to justify the preceding line. PROSE will 
hyphenate such a word if you have defined the syllable boundaries within it. Of course, 
not all the syllable boundaries need be specified, only those at which you want PROSE 
to be able to split a word. For example, if the hyphenation character is the slash */’» y° u 
may type “syncopation" as syn/co/pa/tion. PROSE will insert a hyphen - only when 
the characters on both sides of the hyphenation point are letters. This restriction allows 
you to type “hyper-active” as hyper-/active, and PROSE will split the word if necessary, 
without adding a superfluous hyphen. If PROSE is forced to insert blanks beyond a certain 
threshold set by the OPTION directive, PROSE will issue an error message on the line that 
needs hyphenation characters. 

C: To produce mixed-case output from upper-case-only input, you must specify a case-shift 

character in the INPUT directive parameter, causing PROSE to automatically shift all 
upper-case letters to lower case. To preserve certain upper-case letters, such as initial 
capitals for names and sentences, you can surround the letter or letters with case-shift 
characters. PROSE shifts to upper case for all characters between case-shift characters. 
“Stuttering" is another way to designate capitals among upper-case-only input. Since most 
upper-case letters are at the beginning of a word (following a blank), you use two letters 
to indicate a single capital. Words that already begin with a double letter will produce a 
single capitalized letter unless you put two case-shift characters before the word. 

5-43 









PROSE: A Text Formatter 


Input to Pr: Output from Pr: 


""LLAMA 
—OOPS 
LLLAMA 
000PS 


llama 

oops 

Llama 

Oops 


The following example demonstrates both ways of producing mixed-case output from upper- 
case-only input. The case-shift character is easier to use for long strings, such as example 
programs, that are to be capitalized. Stuttering is easier when you want to capitalize a 
single character, such as the first word of a sentence. You can use both methods in the 
same text as shown below. 

Input to PROSE: 

.INPUT(C") 

HHE HAD EIGHTEEN MINUTES, PLUS THE LOCAL CONNECTION. TTWENTY-ONE 
MINUTES. AA WORLD OF TIME ON A COMPUTER. HHE WAS READY WITH HIS 
HUESTIONS. 

-WHAT IS CODE FOR PROGRAM?" 

"COMPUTER BANDIT." 

"WHAT IS KNOWN ABOUT COMPUTER BANDIT?" 

TTHE SCREEN RAPIDLY FILLED WITH THE DATES AND AMOUNTS OF HIS 
AAMERICAN EEXPRESS THEFTS. SOME OF HIS RECENT INFORMATION SCANS, 

THE REPORTS TO THE NEWSPAPERS IN NNEW YYORK. 

Output from PROSE: 

He had eighteen minutes, plus the local connection. Twenty-one 
minutes. A world of time on a computer. He was ready with his 
questions. 

WHAT IS CODE FOR PROGRAM? 

COMPUTER BANDIT. 

WHAT IS KNOWN ABOUT COMPUTER BANDIT? 

The screen rapidly filled with the dates and amounts of his American 
Express thefts, some of his recent information scans, the reports to 
the newspapers in New York. 

For conversion of mixed-case input to upper-case-only output, see the OPTION directive. 

U: Text surrounded by the underline character will be underlined. Blanks are not under¬ 

lined, but explicit blanks are. 

D: The directive escape character is placed in the first column of an input line to flag it 

as a directive. Use this option only to define a directive escape character other than the 
period. 

W: The input width W specifies the number of characters to be read from each input line. Users 

will only need to change the input width for special jobs. 

K: The keep option explicitly specifies the keep buffer to be used to store the new input options. 

By default, PROSE uses the numerically next buffer. (See “Changing The Format Control 
Directives” for detailed explanation of the use of keep buffers in PROSE directives.) 

OPTION Directive 

The OPTION directive gathers together miscellaneous options that affect the filling and justifying 
PROSE does during text formatting. These options are summarized in the following table. Key 
letters are followed by a switch symbol (+/-) or an integer, as shown in the default column. For the 
switch-type options, the plus sign *+’ means on and the minus sign means off. 
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Key Letter 

Meaning 

Default 

E 

Print error messages 

+ 

J 

Justification limit 

3 

F 

Fill output lines 

+ 

L 

Left justify 

+ 

R 

Right justify 

+ 

S 

Spacing 

1 

M 

Multiple blanks 

+ 

P 

Two blanks after periods 

+ 

U 

Shift to upper case 

- 

K 

Keep 

next 


As processing begins, PROSE assigns the default value for each option without a specified value. A 
parameter value changes only when a specification is given. No option uses relative values. 

E: Error messages appear in the formatted text of the main output files at the approximate 

location of the errors. Error messages are suppressed when this option is off (E-). 

J: PROSE inserts blanks as needed to justify the left and right margins of an output line. 

The justification limit controls the point at which PROSE will attempt to hyphenate 
a word. If, for instance, the justification limit is set at 3, then the hyphenation process will 
be invoked when PROSE has to insert three blanks between adjacent words on a line. If 
hyphenation is not possible, or PROSE is not able to bring the number of inserted blanks 
below the limit, an error message is printed for the line(s). 

NOTE 

Settings for options E and J can be varied according to the draft you are working 
on. Setting J to an arbitrarily high number (e.g., 20) and turning off E helps you 
to avoid hyphenation errors until you are ready to deal with them, usually in the 
later stages of document preparation. 

F: Output lines are automatically filled and justified as described in the “PROSE Basics 

section. If the fill option is off, PROSE will print the input lines as they are, without 
reformatting to fill the output lines. In effect, a justification break is done after each input 
line. Option F- is most useful for literal text, such as program examples, where spacing 
between words must be exactly as typed. 

L: The left and right justify switches work together to determine the justification to be 

R: done. If both options are on, output lines are justified to both the left and right margins. 

If both options are off, the lines are centered between the two margins. If one is on and 
the other is off, one margin (either left or right) will be straight and the other ragged. The 
following examples demonstrate the output from the four combinations. 

Output from .0PTI0NC L+ R+ ) : 

Eddie did four more operations, three of them involving county and 
city payroll checks, all of which were handled by the same computer. 

Output from .0PTI0N( L- R- ) : 

He gave an across-the-board raise of fifty dollars per check to all 
teachers in the ghetto schools. He deducted an equivalent amount from 
the checks of the city's highly paid political appointees. 

Output from .0PTI0N( L+ R- ) : 

Then he erased the tapes for outstanding private residential water 
bills. People, he decided, shouldn't have to pay for a drink of water 
or to be able to flush ... a toilet. 
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Output from .OPTIONC L- R+ ) : 

The final operation was one he hadn*t thought of earlier; it had come 
to him during the night's work. It was easy enough with the 

information he now had. 

S: The spacing option 2 generates double-spaced output; the spacing option 3 generates 

triple-spaced output. By default, text is single-spaced. 

M: If the multiple blanks option is on (M+), multiple blanks in the input file are considered 

to be significant. That is, if several blanks are placed between two words in the input file, at 
least that many will appear in the output file; PROSE may add blanks during justification. 
If the option is off, multiple blanks will be treated as a single blank. 

P: The 2 blanks after periods option places at least two blanks after every period. PROSE 

will not add blanks before justifying if two are already present. This makes for consistent 
spacing in the final copy even if you are not careful about typing 2 spaces after sentence 
periods in the original. Three or more blanks after a period are treated as multiple blanks. 

U: For output devices that cannot process mixed-case files, the shift to upper case option 

shifts all lower-case letters to upper-case letters. This option is also useful for printing an 
entire passage or example, such as a sample program, all in upper case. For conversion of 
upper-case-only input to mixed-case output, see the INPUT directive. 

K: The keep option explicitly specifies the keep buffer to be used to store the new options. 

By default, PROSE uses the numerically next buffer. (See “Changing Format Within the 
Text” for use.) 
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Setting Up the Document’s Format 

This section explains the use of directives to format text. These directives specify page format, 
margins, paragraphing conventions, justification breaks, and blank or comment lines. 


Page Format 

The FORM directive defines the page format, including insertion of titles, date/time, blank lines, page 
numbers, and other textual items at the top or bottom of the page. The FORM directive works with 
the COUNT, TITLE, and SUBTITLE directives. The PAGE and PARAGRAPH directives can override the 
page-break function of the FORM directive. 


FORM Directive 

The FORM directive can produce a variety of page formats, depending upon the options specified in 
its parameter. The table below contains the available FORM options; the following paragaphs explain 
their use. 


Key Char 

Meaning Default Field Width 

[ 

Define top of page 

-none- 

] 

Define bottom of page 

-none- 

#n 

Tab forward or backward to absolute column n 

-none- 

S 

Subtitle 

its length 

T 

Main title 

its length 

Ln 

Fill in n lines of running text on the page 

-none- 

/ 

Print an end of line (by itself, a blank line) 

-none- 

In 

Print n ends of lines 

-none- 

Pf 

Current page number, f selects the form: 

N or n Arabic numerals (default) 

L Upper-case letter 

1 Lower-case letter 

R Upper-case Roman numerals 

r Lower-case Roman numerals 

3 

[The field 
width will 
be expanded 
if needed] 

i i 

Print material within quotation marks as literal text 

-none- 

C 

24-hour clock as hh.mm.ss (e.g. 15.37.58) 

8 

D 

Raw date as yy/mm/dd (e.g. 82/02/13) 

8 

E 

Nice date as dd Mmm yy (e.g. 13 Feb 82) 

9 

V 

Wall clock as hh:mm PM or hh:mm AM (e.g. 3:37 AM) 

8 


If the FORM directive is omitted completely, PROSE uses the default form: 

.FORMC [ // T #62 E III LE4 III #33 •- ' PN:1 1 -• //// ] ) 

The sequence of options within parentheses corresponds to the format of the page from top to 
bottom. The FORM directive builds text lines from left to right, starting in the first printable column 
unless a tabbing specification (#n) starts text at a specific column. 

FORM directive parameters generally begin and end with the definition characters for a top-of-page 
and bottom-of-page. The top-of-page definition ‘ [’ has several uses. You can direct PROSE to send 
a page eject to the output device when it reaches the top of a page. Also, you can request a pause 
at the top of each page to allow you to change paper on the printer (see information on the OUTPUT 
directive in “Printing the Document”). At the end of the document, PROSE signals one last page 
eject and continues to interpret the FORM specification until it reaches another top-of-page. This 
ensures the execution of any commands specified for the bottom of the last page, such as a page 
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number. PROSE increments the page number at the bottom-of-page character T-So, if you print 
the page number both before and after the bottom-of-page definition, you will get different numbers. 

To print slightly differing formats for facing pages, specify a format for each page between a pair of 
page definition characters. For example, this form directive prints the page number at the bottom 
right of odd numbered pages and at the bottom left of even pages. 

.FORM ( [ // T #62 E III L66 // #63 'PAGE' P III 3 

+ [ // T #62 E III L66 // 'PAGE 1 P /// ] ) 

Appendix A contains another example of the FORM directive used to print facing pages. 

Page length is determined by the specification for the number of lines. PROSE breaks pages at the 
number of lines set by the FORM directive’s Ln specification, unless the PAGE directive or the optional 
automatic page eject for the PARAGRAPH directive is used (see “Page Breaks”). If the Ln specification 
is omitted entirely, PROSE supplies the default value of 54 lines per page. If the FORM directive 
parameter contains a key letter L without a value, no special page formatting is done. Page length 

will be infinite, which is useful for working with documents on terminals, where pages are irrelevant. 

In this mode, a PAGE directive with no parameter will put 5 blank lines between sections of text. 

Titles, subtitles, page numbers, and dates are placed in fields at the top or bottom of the page. 
Although default values are sufficent for most situations, the field width can be set to a particular 
value by placing a colon and the value after the key letter. For example, T:30 prints the title in a 
field of 30 characters. Specified field widths are sometimes useful for truncating long titles. PROSE 
fills the field from right to left. The tabbing specification #n places the field horizontally on the page. 

The FORM argument is re-scanned as each page of output is produced, so that any change in a title 
buffer made with the TITLE or SUBTITLE directive will insert the new title or subtitle on the next 
page. The TITLE directive enters the remainder of the line into the main title buffer. The FORM 
directive uses the contents of the title buffer to print a title on the page as specified. The SUBTITLE 
directive enters the remainder of the line into the subtitle buffer, to be used by the FORM directive 
to print a subtitle on the page as specified. See examples in Appendix A. 

PROSE adds a blank line for each 7’ mark in the FORM directive. These blanks are placed uniformly 
on each page, in the relative position that they appear in the directive, usually at the top and 
bottom, between the body of the text and the title and page number. The alternative /n allows a 
shorter expression of numerous blank lines; either form may be used. 

Page numbers are incremented by the page counter and placed on the page by the Pf option of the 
FORM directive. The COUNT directive sets the page counter. The integer in the COUNT parameter can 
be a relative value; for example, .COUNT +1 increments the page number by one. By default, the 
page counter sets the page number to 1. 

The literal text option allows you to add such touches as hyphens surrounding the page number 
(see default FORM directive) or other text that must appear exactly as typed. For example, suppose a 
press release required the word “more” with parentheses around it at the bottom of each page. You 
could use the literal text specification as follows: 

.F0RM( [ T III L54 III #28 '(more) 1 III 3 ) 

PROSE users may choose between four styles of dates. The date is placed on the page in much the 
same manner as a title. 


Page Breaks 

The PAGE directive signals a page eject when fewer than the specified number of lines remain on 
the current page. If no parameter is given, the PAGE directive does an unconditional page eject. The 
PARAGRAPH directive’s automatic page eject includes the page-break function in the paragraph 
format for the document. .PAGE 3 and .PAR(P3) are equivalent, except that .PAGE 3 must be 
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PARAGRAPH directive’s automatic page eject includes the page-break function in the paragraph 
format for the document. .PAGE S and .PARCPS) are equivalent, except that .PAGE 3 must be 
explicitly placed by the user, while PROSE executes .PARAGRAPH (P3) wherever indicated by the 
paragraph flag character. 


Margins 

The MARGIE directive sets the left and right margins for filling and justifying. The value for left 
nargin indicates the column in which the line of text begins; the right aargin value is the column 
number of the last printed character. Thus, subtracting the left margin from the right margin gives 
the number of columns for printed text. 

The options, which may be given in any order, consist of a key letter followed by a value. The next 
table lists the key letter for each option. 


Key Letter 

Meaning 

Type 

Default 

Relative 

L 

Left margin 

integer 

0 

yes 

R 

Right margin 

integer 

70 

yes 

E 

Keep 

integer 

next 

no 


Margins are set before text processing begins. PROSE assigns default values of LO R70 if no MARGIE 
directive is used or if the directive is given without a parameter. A value changes only when a new 
specification is given. The keep option explicitly specifies the keep buffer to be used to store the new 
margins. By default, PROSE uses the numerically next buffer. 

The IEDEBT directive moves the next line of text to the right of the page by the given number of 
spaces. When the directive is used without a parameter, the default value is 5. The OEDEET directive 
moves the next line a certain number of spaces to the left. (The undent is sometimes known by 
the name “outdent” or “hanging indent.") If the given parameter would undent the text past the 
leftmost column of the printed page, the directive undents only to the leftmost printable column. If 
no parameter is given, the default undents to the leftmost printable column. 


Paragraphs 

Although you may use any justification break methods to distinguish between one paragraph and 
the next, the PARAGRAPH directive provides a more versatile method of creating paragraphs. 

Placed at the beginning of the text, the directive sets the general form of paragraphs and specifies 
a paragraph flag character. Many PARAGRAPH options take the place of other directives, so the 
directive is a powerful tool. 

When the paragraph flag character is placed in the first column of a text line to signal a new 
paragraph, PROSE takes any of the following actions that are specified by the parameter. 


Kev Letter 

Meaning 

Type 

Default 

r 

Paragraph character 

character 

nul 

i 

Automatic indent 

number 

0 

0 

Automatic undent 

number 

0 

H 

Number generator 


-none- 

P 

Automatic page eject 

number 

0 

S 

Automatic skip 

number 

0 

K 

Keep 

number 

next 


5-49 


Updated January 1085 














PROSEs A Text Formatter 


When it begins processing, PROSE assigns the default value for each option in the PARAGRAPH 
directive parameter. If the input file contains no PARAGRAPH directive, or if an option is not specified, 
the default value is used. No PARAGRAPH option uses relative values. 

By manipulating the options in the parameter, you may direct PROSE to take any of the following 
actions for paragraphs. 

F: The paragraph flag character invokes a collection of paragraphing actions when it 

appears in the first column of an input line. Note that this character must be set in the first 
PARAGRAPH directive, or no other options apply. As the only specified option, the paragraph 
flag character signals a justification break. 

I: The autonatle indent or autoaatie undent applies to the first line of the paragraph 

G: and moves the line left or right a given number of spaces. If the number generator is used, 

the indent or undent is applied after the number is generated (see the example using both 
options below). 



I: 


The nunber generator produces a new number (or letter) for each occurrence of the 
paragraph flag character. PROSE inserts the number in lieu of the paragraph flag character 
when the line is formatted, so you must put a space between the paragraph flag character 
and the text line, if you want one to appear in the output. The number generator is 
initialized to 1 each time new paragraph settings go into effect. Resumption of an old 
setting also resumes the old numbering. The number generator’s keyword contains these 
fields (spaces not allowed): 


I numeric-field Beld-widtb 


The key characters for numeric-Beld are: 


-blank- 

I or a 

L 

1 

R 

r 


No numbering 
Arabic numerals 
Upper-case letter 
Lower-case letter 
Upper-case Roman 
Lower-case Roman 


The field width for the numeric field, expressed as an integer, is expanded if necessary. 
If, for example, you want an Arabic numeral with three spaces left for the numeral, the 
keyword is In3. 


The next input and output examples illustrate one style of numbered, undented paragraph 
created with the automatic undent and number generator options. Note that the margin 
adjustment places the paragraph number in the leftmost column of the printed page. 


Input to PROSE: 

HARGIK L10 ) 

. PARAGRAPH ( F* Ini 05 ) 

ft Eddie worried about that one for a while, then case up with 
a very simple answer: he would ask the computers If they had 
any such self-laspectloa instructions in their programs. It 
would become part of his regular greeting: HELLO. HOV ARE TOO 
AID ARE TOO PROGRAMMED TO TRAP MET 
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Output from PROSE: 

1 Eddie worried about that one for a while, then came up with a 
very simple answer: he would ask the computers if they had 
any such self-inspection instructions in their programs. It 
would become part of his regular greeting: HELLO. HOI ABE 
YOU AND ABE YOU PBOGBAMMED TO TRAP ME? 


S: 


The automatic page eject simulates the effect of the PAGE directive. For instance, the 
directive . PAB ( P4 ) causes PROSE to eject a page if fewer than four lines of the paragraph 
are left at the bottom of the page. The command is applied after the automatic skip. 

The automatic skip functions the same as a SKIP directive, placing a blank line before 
the first line of the paragraph. 

The keep option explicitly specifies the keep buffer to be used to store the new paragraph 
options. By default, PROSE uses the numerically next buffer. 

Values and options can be changed for particular paragraphs or sections of the document, as 
explained in “Changing Format Within the Text. 


K: 


Comments 


Using the COMMENT directive, you can include information in the source of atreatsthl 
not be printed in the formatted copy. As shown in the examples m Appendix A, PROSE treats the 

remainder of the line as a comment and ignores it. 


Changing Format Within the Text 

To make the tallest ase of PROSE, the user must manipulate such options as blank characters, 
spacing, margins, or page break, .ithin the text. The BBEAK and SKIP direct.™ alio, yon to 
interrupt the established formatting process. 

At certain points, you may need to switch formats for specific situations, such as example pro^ams 
or blocked quotations. OPTION, MABGIN, and PABAGBAPH settings may change frequently, but the 
number of different settings will probably be predictable and few Depending upon the number, the 
variety, and the frequency of changes the text requires, the following techniques can help you to 
enter new directives or restore previously used options. 

Breaking and Skipping Lines 

One of the simplest and most frequently used instructions, a justification break causes PROSE 
to stop filling the current output line and print it without justifying. A line break can be indicated 
in many ways. Text can be separated (broken) by one or more blank lines inserted in the text, 
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by leading blanks typed on an input line (a paragraph indention), or by the BREAK directive. The 
following example illustrates these three methods. 

Input to PROSE: 

"We've got to feed him an estimate that is believable—" 

"—but totally inaccurate," the IBM man said. 

.BREAK 

"Right," Barstow said. 

.BREAK 

"It's like Battleship." Purvey said, smiling at Barstow 
and the IBM man. 

"You understand perfectly," the IBM man said, "That's 
exactly what it is." 

Output from PROSE: 

"We've got to feed him an estimate that is believable—" 

"—but totally inaccurate," the IBM man said. 

"Right," Barstow said. 

"It's like Battleship," Purvey said, smiling at Barstow and the IBM 
man. 

"You understand perfectly," the IBM man said, "That's exactly what it 
is." 

With any of these methods, you will only direct PROSE to do a justification break. PROSE will not 
skip lines or indent unless you explicitly enter blank lines or indentions in the input file. 

The SKIP directive prints blank lines within the text by skipping a certain number of output lines. 
SKIP will not print blank lines at the top of a page, unless you enter at least one actual blank line 
before the SKIP directive. The default value of the SKIP directive is 5 lines. 


Keep Buffers 

The keep buffer is a simple way to change directives that control input or format. Each time a 
change in one of these directives is processed, PROSE saves the new values in a keep buffer. Ten 
keep buffers (0 through 9) are associated with each directive. You may use a keep parameter to 
specify the buffer to be used; if no buffer is specified, the values are saved in the numerically next 
buffer. To recall a previously used value, you enter the directive with the number of the keep buffer 
as the parameter. 

For example, suppose that a double-spaced text has a number of paragraph-length quotations, which 
are to be typed as single-spaced blocks indented ten spaces from each margin. Using the keep option 
in the parameters for the INPUT, MARGIN, and PARAGRAPH directives, you could store the format 
specifications for each situation in two different keep buffers by entering these directives at the 
beginning of the input file: 

.OPTION(K1 S2).MARGIN(K1 L10 R70).PARAGRAPH( K1 F4 12 SI ) 

Then you enter these directives for the new format 

.OPTION(K2 SI).MARGIN(K2 L20 R60).PARAGRAPH( K2 Fft 10 SO ) 

before the first blocked paragraph. To resume the standard paragraph format, you then enter the 
directive names with the number of the keep buffer. The input and output files would look like this: 
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Input to PROSE: 

.OPTION( K1 S2 ).MARGIN( K1 L10 R70).PARAGRAPH( K1 FA 12 SI ) 

AThere was nothing to be done. He had once heard a comedian 
say, 

.OPTION( K2 SI ).MARGIN( K2 L20 R60 ).PARAGRAPH( K2 FA 10 SO ) 

If you don't like the telephone company, 
you know what you can do? Two tin cans and 
a piece of string, that's what you can do. 

That's the only alternative you've got. 

.OPT 1.MAR 1.PAR 1.SKIP 1 

The people in the audience had laughed. Eddie thought about 
it now and decided it wasn't funny at all. 

Output from PROSE: 

There was nothing to be done. He had once heard a 
comedian say. 

If you don't like the telephone company, 
you know what you can do? Two tin cans 
and a piece of string, that's what you 
can do. That's the only alternative 
you've got. 

The people in the audience had laughed. Eddie thought about 

it now and decided it wasn't funny at all. 

To change format for the next single-spaced, blocked paragraph, you would only need to enter: 

.OPT 2.MAR 2.PAR 2 

The example is a little more cumbersome than is necessary for one format change. Actually, you need 
only enter .OPT.MAR.PAR to return to keep buffer 1 in the text shown above. When no parameter is 
specified, the values are set to those stored in the numerically previous keep buffer, since the keep 
number is automatically incremented whenever a directive is entered and automatically decremented 
when that directive is entered without a parameter. Used in this way, the keep buffers function as 
a “stack” for temporary storage of variations from a basic format. 

Reset Directive 

The RESET directive sets twelve frequently changed directives to their default values. The following 
table summarizes the effect of the RESET directive on each. 
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Directive 

Effect 

INPUT 

Default values for all options. 

OPTION 

Default values for all options. 

FORM 

Default values for all options, 
causes page eject. 

COUNT 

Sets page counter to 1. 

TITLE 

No titles until reentered. 

SUBTITLE 

No subtitles until reentered. 

PAGE 

Causes a page eject. 

INDEX 

Deletes all accumulated entries. 

MARGIN 

Default values for all options. 

PARAGRAPH 

No paragraphing until directive reentered. 

OUTPUT 

No pause at top of page; 
carriage return to do underlining; 
causes page eject. 

SELECT 

Discontinues page selection; 


all pages to be printed. 

The RESET directive can be used three ways: 

• Entering the directive name with no parameter resets the values of all directives to their defaults: 

.RESET 

• Using a directive name as a keyword resets the selected directive. For example, this command 
resets only the MARGIN and OPTION directives: 

.RESET( MARGIN OPTION ) 

• Stating the keyword “except” and a directive name in the parameter excludes a selected 
directive. For example, this directive resets all directives with the exception of FORM and OUTPUT: 

.RESET( EXCEPT FORM OUTPUT ) 

New directives may be entered after the RESET directive. The RESET directive is an easy way to clear 
a complicated series of format changes from the keep buffers. 


Creating An Index 

The INDEX and SQRTINDEX directives provide the information PROSE needs to create an index for 
the document. The INDEX directive is entered as . INX to distinguish it from . INDENT and takes the 
remainder of the line together with the current page number as an index entry. As the formatted 
text migrates from page to page in various drafts, the page numbers in the index are updated. 

Index entries accumulated by INX directives can be sorted alphabetically or by page number, then 
printed in a relatively flexible manner. The SQRTINDEX directive allows you to specify the method 
of sorting entries and the format for printing the index. 

The options for the SQRTINDEX directive, listed in the following table, may be given in any order. 


Key Letter 

Meaning 

Default 

S 

Sorting option. If this is numeric, it is the first 
significant column for alphabetic sorting. If it is 
the letter P, sorting is selected by page number. 

1 

M 

Margin (left margin before index line) 

0 

P 

Column (in index entry) to insert page number 

0 

L 

Left width of page number (field width of number) 

2 

R 

Right width of page number, blanks printed after 
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In the absence of a parameter, default values are used. 


Printing the Document 

This section does not anticipate all the possible idiosyncracies of the PDP-11 and its peripherals; it 
gives you directions for printing all or part of the document on certain standard devices. 


Specifying Output Devices 

The OUTPUT directive defines important aspects of the output device to which you will send the 
formatted text. The directive takes the general form: 

. OUTPUT (device, options...) 

All of the following is specific to the PDP-11. 

One of the following acronyms indicates the output device to be used. 

ASC ASCII terminals use the backspace for underlining, but are otherwise the same as the 
lineprinter (LPT) below. Pauses for page eject, however, are handled differently (see the P 

option below). 

LPT Line printers use overprinting with a carriage return to do underlining. This is the default 
output device. 

The following table contains the options for each output device. Keyword type is an integer or a 
switch. 

Key Letter Meaning Defau lt 

E Page eject at top of page 

( [ in FORM description) 
p Pause at top of page 

S Shift output lines to the right 0 

U Underlining is available + 

These options may be given in any order. 

E: The page eject option prints a form feed character for each time PROSE reads [ in the 

FORM specification. 

P . The pause option causes PROSE to stop printing and await operator acknowledgement 
each time a T character is encountered in the FORM specification. On an ASC terminal 
PROSE will sound the bell and wait for a carriage return to be entered. For an LPT output 
device, no action will be taken. 

S: The shift option shifts all PROSE output to the right by any number of spaces up to 50. 

This makes it easy to center output on a wide printer page. 

U- If the destination terminal does not have underlining capability and the input file contains 
underline characters, the underlining available option should be turned off to prevent 
PROSE from trying to generate overprinted underlines. 

Usually, the OUTPUT directive appears only at the beginning of the input file or in a header file. 
However, it must also be used immediately after a . RESET (OUTPUT) directive. 

The LITERAL directive is useful for producing special printer control characters on some systems. It 
prints the remainder of the input line as a single output line, after special processing for upper and 
lower case, underlining, and literal blanks. This single line is printed independently of filling and 
justifying, or page-formatting processes; it is not counted as an output line. 
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Printing Selected Pages and Sections 

The SELECT directive will print specified pages of a document. Like the OUTPUT directive, the SELECT 
directive is placed before any lines that are to be printed on the output device, perhaps in a header 
file. Although the entire text will be formatted, only the selected pages will be printed, saving 
unnecessary printing time. 

The parameter consists of page numbers separated by spaces. Two page numbers separated by a 
colon will select the span of pages, including beginning and ending numbers. As shown below, the 
plus sign *+* specifies a second page number relative to the first. The following example prints pages 
3, 5, 10 through 15 inclusive, and 20 through 25 inclusive. 

.SELECT( 3 5 10:15 20:+5 ) 

By default, all pages are printed. 
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Appendix A: Examples of PROSE Directives in Text 

Example 1. 

Input to PROSE: 

.OUTPUT (LPT U+ E+) 

.COMMENT --* 

.COMMENT I NOTE: The header file supplied by Oregon Software I 
.COMMENT |contains the output co mma nd for the line printer. 

.COMMENT IDo not use the above command if using that header. I 

.COMMENT -- - 

.FORM ([ // #10 Pn #28 T III LBO //// ] 

+ [ // #60 Pn #17 S III L50 //// ]) 

.COMMENT Page numbering starts at 62 
.COUNT 62 

COMMENT This combination of form and count directives 
.COMMENT duplicates the facing-pages format used in the 
.COMMENT many typeset books. 

.COMMENT 

.TITLE The Programmer 
.SUBTITLE Chapter Three 
.MARGIN(L10 R62) 

.INPUT (H/ U_) 

.PARAGRAPH (FA 12) 

^Computers, Eddie knew, have no idea where their sources of 
information are in the world. They look upon the world as one great 
big fat wire bulging with information and instructions, a wire with 
no beginning, middle, or end. The world for a computer is merely an 
electrical input saying. "Here's what you should know." or. "Here's 
what I want to know. "or. *'Here's what you are to do now, " and an 
electrical output for them to talk back: 

"Here's what I must know to answer your question," and. "Here are 
your answers." To the computers, all interrogators and commanders 
speak with the same voice and the same authority; all listeners have 
the same ear. 

ALike guns. It doesn't matter to a gun who pulls its trigger. Guns 
have awesome power, but they are entirely dependent on the hands that 
use them. Morally guns and computers are out of it all, though they 
are regularly the instruments for people who make things happen. 

ATwice now—first with Betty's parking ticket and now with his 
$25.624.34—Eddie had been someone who made things happen. It was 
a very exciting sen/sa/tion. one he hadn't previously experienced. 

AHe had seen, not long before on the "Today" show, an airline pilot 
who talked about his af/fec/tion for the 747. He loved it more, he said 
than any other aircraft he had ever flown, and he had been a pilot for 
twenty-five years. The inter/view/er asked him to explain his 
enthusiasm. 

A"I sit there in that little room in the front," the pilot said, "a 
room just four stories off the ground when we're parked, but at the 
top of the world when we're in flight—and I move litle knobs and 
dials. None of them takes more than a few ounces of pressure. 
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In an instant a machine weigh/ing a hundred tons responds more smoothly 
than if I were mowing it myself. It's like the aircraft becomes an 
extension of myself because so little effort is needed to make it do 
what I want, and it does whatever I want it to do. It's very 
ex/cit/ing. 1 ' 

ft 41 You make it sound almost sexual, 11 the inter/view/er said. 
ftThe pilot frowned. “I don't know about that. I never thought about 
that." His face brightened. "It's not sex. It's better. It's .real, 
power.'' 

ftEddie sensed that his entire relationship with the computer had 
started a radical change. Before, he had been the machine's servant, 
bringing it little orders and loads of information to feed upon. The 
questions weren't his and the answers never mattered to him. He was 
merely an intermediary in the affairs of others. Now he was having 
his own affair. 

ftAnd his own affair required further action before the check in his 
pocket became anything but a useless piece of paper. 

.SKIP 2 

ftOn his way back to the office Eddie stopped in the motor vehicle 
section. Edna was there alone, as usual, talking on the telephone, 
also as usual. She was wearing a different pink sweater. She held up 
her hand, the fingers all extended. At first Eddie thought she was 
showing off her rings—there were four of them, all different but 
then he understood that she was telling him she would be on the phone 
five minutes longer. He waved his hand to indicate he was in no hurry. 
She leaned back in the chair, her pink breasts pointing toward the 
corner light fixture. 

ftEddie wandered around the office, acting as if he were bored. He 
looked at some papers. She was paying no attention to him. He stopped 
at the drawer where blank drivers' licenses were kept. He looked over 
his shoulder. She was still talking, her back to him. Her left hand 
held the telephone and her right hand slowly rubbed the back of her 
neck. 

ftHe quickly took from the drawer ten forms, then leaned on the 
counter and quietly stamped each of them with the tricolored state 
seal required for validation. He put the forms into his jacket pocket 
along with the two checks. Now he had only to type out whatever names 
he wanted to use and he would have official New York certification. 
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Output from PROSE: 


62 


The Programmer 


Computers, Eddie knew, have no idea where their 
sources of information are in the world. They look 
upon the world as one great big fat wire bulging 
with information and instructions, a wire with no 
beginning, middle, or end. The world for a computer 
is merely an electrical input saying, ‘‘Here's what 
you should know,' 1 or, “Here's what I want to 
know, 1 ' or, “Here's what you are to do now," and 
an electrical output for them to talk back: “Here's 
what I must know to answer your question,'' and, 
“Here are your answers.'' To the computers, all 
interrogators and commanders speak with the same 
voice and the same authority; all listeners have the 
same ear. 

Like guns. It doesn't matter to a gun who pulls 
its trigger. Guns have awesome power, but they are 
entirely dependent on the hands that use them. 
Morally guns and computers are out of it all, though 
they are regularly the instruments for people who 
make things happen. 

Twice now—first with Betty's parking ticket and 
now with his $25,624.34—Eddie had been someone who 
made things happen. It was a very exciting sensa¬ 
tion, one he hadn't previously experienced. 

He had seen, not long before on the “Today* ' 
show, an airline pilot who talked about his affec¬ 
tion for the 747. He loved it more, he said, than 
any other aircraft he had ever flown, and he had 
been a pilot for twenty-five years. The interviewer 
asked him to explain his enthusiasm. 

“I sit there in that little room in the front,' 1 
the pilot said, “a room just four stories off the 
ground when we' re parked, but at the top of the 
world when we're in flight—and I move litle knobs 
and dials. None of them takes more than a few 
ounces of pressure. In an instant a machine weigh¬ 
ing a hundred tons responds more smoothly than if I 
were moving it myself. It's like the aircraft 
becomes an extension of myself because so little 
effort is needed to make it do what I want, and it 
does whatever I want it to do. It's very excit¬ 
ing. ' ' 

“You make it sound almost sexual, 1 ' the inter¬ 
viewer said. 

The pilot frowned. “I don't know about that. I 
never thought about that.'' His face brightened. 
“It's not sex. It's better. It's real power.' 1 

Eddie sensed that his entire relationship with the 
computer had started a radical change. Before, he 
had been the machine's servant, bringing it little 
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Chapter Three 33 

orders and loads of information to feed upon. The 
questions weren't his and the answers never mattered 
to him. He was merely an intermediary in the 
affairs of others. Now he was having his own 
affair. 

And his own affair required further action before 
the check in his pocket became anything but a 
useless piece of paper. 


On his way back to the office Eddie stopped in the 
motor vehicle section. Edna was there alone, as 
usual, talking on the telephone, also as usual. She 
was wearing a different pink sweater. She held up 
her hand, the fingers all extended. At first Eddie 
thought she was showing off her rings—there were 
four of them, all different—but then he understood 
that she was telling him she would be on the phone 
five minutes longer. He waved his hand to indicate 
he was in no hurry. She leaned back in the chair, 
her pink breasts pointing toward the corner light 
fixture. 

Eddie wandered around the office, acting as if he 
were bored. He looked at some papers. She was 
paying no attention to him. He stopped at the 
drawer where blank drivers' licenses were kept. He 
looked over his shoulder. She was still talking, 
her back to him. Her left hand held the telephone 
and her right hand slowly rubbed the back of her 
neck. 

He quickly took from the drawer ten forms, then 
leaned on the counter and quietly stamped each of 
them with the tricolored state seal required for 
validation. He put the forms into his jacket pocket 
along with the two checks. Now he had only to type 
out whatever names he wanted to use and he would 
have official New York certification. 
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Example 2. 

Input to PROSE: 

.COMMENT Output directive is in the header file. 

.INPUT( B# H/ ) 

.OPTION( K1 ) 

.FORMC [ // #50 I #80 E III L50 / #30 ' PN:1 1 -' ] ) 

.MARGIN( K1 L5 R70 ) 

.PARAGRAPH( K1 FA SI ) 

ASomething clicked in another part of his mind and he knew he was about 
to become a portable computerized superpower. 

A The question had been puzzling him for some time. It had to do with 
pro/gram access. If one had a pro/gram—if one lmew the para/dig/matic 
structure of a set of encoded information—then one could do nearly 
any/thing one wanted with that information. If it was simply material 
stored, then one could learn everything that was stored; if it was 
operational material, then one could command the operations. The 
problem was, one needed the program to do the work, and the utility 
of the programs he had taken with him when he left Buffalo was 
limited. 

AThe cold water swirled around his legs and the ripples moved out from 
where his hands paddled the surface. Suddenly it was as if the answers 
had typed themselves out on the console screen. 

.0PT( K2 U+ S2 ) 

.MARC K2 L15 ) 

.PARAGRAPH( K2 FA U8 SI ) 

AQUESTION:##H0V DO I FIND OUT IHAT PROGRAMS EXIST 
THEN I DON’T KNOT THAT QUESTIONS TO ASK? 

AANSTER:##ASK THE COMPUTERS THAT QUESTIONS THEY CAN 

ANSTER FOR YOU. IF YOU HAVE THE ANSBERS, YOU KNOT THE QUESTIONS. 

.OPT.MAR.PAR 

AHe ran home through the woods without even bothering to 
dry off. Mosquitoes pecked at his face. He dressed quickly, 
hooked up the van, and sat down at his keyboard. He addressed 
IFFI, the central law enforce/ment computer in Baltimore. The 
acronym stood for Information#Filed#for#Future#Investigations. 

He asked IFFI a question that translated as, “That discrete 
sets of information have you on hand and what are the access codes 
for them? 1 ' He set the machine for a printout rather than a 
readout on the monitor. 

Ain seconds the Selectric began typing away. It typed for a long 
time. Office Selectrics can handle about thirty characters a 
second, faster than any human can go, but the ones built for 
information processing wont three times as fast. Nearly 
one thousand five-/character units of information a minute, and 
the machine seemed to be typing faster than he had ever seen it 
go before... 
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Output from PROSE: 


3:35 PM 14 Jun 82 


Something clicked in another part of his mind and he knew he was 
about to become a portable computerized superpower. 

The question had been puzzling him for some time. It had to do 
with program access. If one had a program—if one knew the 
paradigmatic structure of a set of encoded information then one 
could do nearly anything one wanted with that information. If it 
was simply material stored, then one could learn everything that 
was stored; if it was operational material, then one could 
command the operations. The problem was, one needed the program 
to do the work, and the utility of the programs he had taken with 
him when he left Buffalo was limited. 

The cold water swirled around his legs and the ripples moved out 
from where his hands paddled the surface. Suddenly it was as if 
the answers had typed themselves out on the console screen. 

QUESTION: HOW DO I FIND OUT WHAT PROGRAMS EXIST WHEN I DON'T 
KNOW WHAT QUESTIONS TO ASK? 


ANSWER: ASK THE COMPUTERS WHAT QUESTIONS THEY CAN ANSWER FOR 
YOU. IF YOU HAVE THE ANSWERS, YOU KNOW THE QUESTIONS. 


He ran home through the woods without even bothering to dry off. 
Mosquitoes pecked at his face. He dressed quickly, hooked up the 
van, and sat down at his keyboard. He addressed IFFI, the 
central law enforcement computer in Baltimore. The acronym stood 
for Information Filed for Future Investigations. He asked IFFI a 
question that translated as, ''What discrete sets of information 
have you on hand and what are the access codes for them? 11 He set 
the machine for a printout rather than a readout on the monitor. 

In seconds the Selectric began typing away. It typed for a long 
time. Office Selectrics can handle about thirty characters a 
second, faster than any human can go, but the ones built for 
information processing went three times as fast. Nearly one 
thousand five-character units of information a minute, and the 
machine seemed to be typing faster than he had ever seen it go 
before... 
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Appendix B: Summary Directive Table 


Directive 

Meaning (action) B 

BREAK 

Break justification 

COMMENT 

No action 

COUNT 

Set page count 

FORM 

Define page format 

INDENT 

Indent following line 

INPUT 

Specify input options 

INX 

Store index entry 

LITERAL 

Print literal text 

MARGIN 

Set margins 

OPTION 

Set options 

OUTPUT 

Specify output device 

PAGE 

Eject to top of page 

PARAGRAPH 

Set paragraphing params 

RESET 

Reset directive defaults 

SELECT 

Select pages to print 

SKIP 

Skip output lines 

SORTINDEX 

Sort and print index 

SUBTITLE 

Set the subtitle 

TITLE 

Set the main title 

UNDENT 

Undent following line 


* 

* 

* 

* 


-none- 

remainder of line 
numeric 
(...) 

numeric 

( ...) or numeric 
remainder of line 
remainder of line 
( ...) or numeric 
( ...) or numeric 

(•••). 

numeric 

(...) or numeric 

(...) 

(...) 

numeric 

(...) 

remainder of line 
remainder of line 
numeric 


-none- 
-none- 
.COU 1 

,F0R([ /2 T #62 E /3 L54 
+ /3 #33 •-* PM:1 /< D 

-none- 

,INP(D.I1B0 K+l) 

-none- 
-none- 
.MAR(LO R70) 

.OPT(SI F+ M+ P+ L+ 

+ R+ J3 E+ U- K+l) 

.OUT(LPT. SO U+) 

.PAG B 
-none- 
-none- 
-none- 
-none- 

.S0R(S1 L2 R2) 

-none- 

-none- 

-none- 


The directives marked »ith an asterisk ( > ) cause a justUication break before they are processed, 
since they affect the filling and justifying environment. 

The ellipsis ( ... ) indicates that the parameter is enclosed in parentheses and is descrrbed ,n detad 
along with the description of the directive itself. 
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Appendix C: Historical Notes 

Most text-formatting programs available today descend from one of several original programs. 
Among these is RUNOFF, developed on the Dartmouth Time-Sharing System in the 1960s. Later, 
the Call-a-Computer system provided a RUNOFF version called EDIT RUNOFF as a text-editor 
command. In 1972, Michael Huck, working on the University of Minnesota’s MERITSS system (a 
CDC 6400 running the KRONOS operating system), began to develop a version of EDIT RUNOFF 
called TYPESET. 

TYPESET was intended as a “versatile text information processor commonly used to typeset 
theme papers, term papers, essays, letters, reports, external documentation . . . , and almost any 
other typewritten text.”* In spite of these aspirations, no program can be all things to all people. 
TYPESET went through many changes, stablizing somewhat in early 1977 at version 5.0, which is 
written in CDC COMPASS assembly language. John P. Strait developed PROSE, written in Pascal, 
over a year’s time starting in the spring of 1977. The design was influenced heavily by TYPESET, 
making PROSE one of the many descendants of RUNOFF. 

PROSE, with minor changes, was installed on the Univac 1100 series computers in early 1980 by 
Michael S. Ball of the Naval Ocean Systems Center. At Oregon Software, he converted this version 
from the Univac to the PDP-11 in July 1980 and to the Motorola MC68000 in the spring of 1982. 


* Michael Huck, Typeset 5.0 Information , © 1977. 
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for More Information 


Prices are subject to change without notice. 

aovic. programmer. (W. W. Nortoa, HU*) 

Peogramm/ogm^e^^Gr.^oo^ ^ ^ ^ for experimeata. 

Uoa. (Oregoa Software eappliee oae copy to each new easterner.) 

fotroductam*Bj«, b^Rodaay M* ^.tood by everyoae. (SYBEX 

Lnc., $14.95) 

A User o^idieUNKopCTathigsyrftei^OSBCHtNE/McGraw-Hil,, J15-99) 

UNIX Programmer’s Manual Seventh EAton,1 ofthToperating system and its utility programs; 
for new users. (Bell Laboratories, $60.00 for Volumes 2A and 2B) 

Pascal ° ne C ° Py t0 eaCh 

new customer.) 

Algorithms + Data Structures “ Pro *"“°“iro ct , ^ts lU i^ , odtg with records, arrays, aad sets — 

programs. (Pre.tie.Ha,,, «W) 

Structured Programming by Dahl, Dijkstra, Hoare. modelliag (Dijkstra), data structur* 

4 id Hoar,,. (Academic 

Press, $20.00) 

Elements of Programming Style by Kermghan and PljuP^ program ming and the use of 

irritTh”:^^"^:,, 0 ,! u: A- -«—- 

on programming. (McGraw-Hill, $3.95) 
tical study of coding. (Prentice-Hall, $23.95) 

SS=r-^s:=:= 
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For More Information 


the UUCP network. (Bell Laboratories, $100.00 includes Volumes 1, 2A, and 2B) 

Concurrent Euclid , the UNIX System, and Tunis by Holt, Graham, Lazowska, Scott. 

An introductory text on concurrent programming, the techniques used to design and 
implement operating systems, computer networks, real-time control and embedded 
microprocessor systems. (Addison-Wesley, $15.95) 

Pascal Newsletter 

Published quarterly, Oregon Software’s Pascal Newsletter, which contains status reports 
on all of our Pascal products, announcements of new versions of software and new 
products, and various technical articles. 


Temporarily, the newsletter is the sole publication for the Oregon Pascal Users Society 
(OPUS), an organization dedicated to the sharing of information between Oregon 
Software and its customers. Oregon Software is not affiliated with OPUS, but we en¬ 
courage its activities and provide space for an OPUS column in our Pascal Newsletter, 
until OPUS begins to publish its own newsletter. OPUS membership is free. To join, 
write: 


Oregon Pascal Users Society (OPUS) 
Bruce Williams 
c/o EOCOM 
15771 Redhill Ave. 

Tustin, California 92680 
(714) 730-5051, ext. 302. 


The Pascal Newsletter 

Published by the Pascal Users’ Group, The Pascal Newsletter, is available at $10 
for a one-year subscription. Contact: 

Pascal Users’ Group 
2903 Huntington Rd 
Cleveland, Ohio 44120. 
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Style note: Page numbers in boldface (6) indicate the defining use of the term. 


A 

alignment, byte boundaries, 2-33 
allocating memory, 2-24 
alphabetize, tee structure, manual 
ASCII format, 3-6 
assembly language, tee PASMAC 


B 

biteize function, 2-34, 3*21 
Blaise Pascal, 1-2 
boolean operators, 3-18 
boundary, alignment of user-defined types, 
2-33 

breakpoint, 1-7, tee alto Debugger,breakpoint 
commands 

break procedure, 3-16 

/buff :n I/O control switch, 3-® 

Bug Reports, tee Trouble Reports 


C 

cache memory, 2-28 
case statement, 3-13 

example with othervlee, 3-13 
otherwise clause, 3-13 
chaining, 2-23 

channels, input and output, 2-19 
overlay load, 2-16 
characters, data type, 3-6 
character strings, tee Dynamic String Package 
literal, 3-4 

check compilation switch, 2-3 
Icheck embedded switch, 2-7 
chr function, 3-30 
Clancy, Mike, Info-1 
close procedure, 3-15, 3-26 
colon notation, 2-2, 2-5 
command lines, reading of, 2-46 
consent PB switch, 5-9 
compilation, 1-1 

errors, 1-2, 2-62, tee alto error mes¬ 
sages 

examples, 1-1, 2-7 
syntax, 2-1 

compilation switches, 1-4,1-3 
check switch, 2-3 


debug switch, 1-6, 2-3, 2-60, 4-2 
double switch, 1-8, 2-2, 2-18 
errors switch, 1-4, 2-3 
list switch, 1-4, 2-3 
■aero switch, 2-3, 2-19 
■aim switch, 2-2 

no- reverses effect of <switcb>, see 
< switch > 
object switch, 2-3 
on switch, 2-2, 3-8 
profile switch, 1-8, 2-3, 4-32 
standard switch, 2-3 
test switch, 2-3 
tines switch, 2-3 
ualkback switch, 2-2 
workspace switch, 2-2 
pascall switch, 2-2 
compiler directives, fiaclude, 3-8 
compiler errors, 2-76 

consistency checks, 2-76 
overflow, 2-76 

compiler installation, tee Release Notes 
compiler optimizations, tee optimization 
concatenation of source files, 2-1, 2-23, 
5-18 

conformant array parameters, xhr, 3-2 
examples, 3-4 
syntax, 3-3 

constants, structured, 3-9 
COISTS psect, 2-22 
Cooper, Doug, 1-1, Info-1 
cross-reference utilities, 5-13 

PROCREF procedure lister, 5-15 
XREF identifier lister, 5-13 
customized error messages, 2-39 


D 

Dahl, O.-J., Info-1 

debug compilation switch, 1-6,2-3,2-60, 
4-2 

tdebug embedded switch, 2-5 
Debugger, 4-1 

assigning values to variables, 4-14 
breakpoint commands, 4-6 
breakpoints, 1-7 
command summary, 4-31 
data commands, 4-13 
debug compilation switch, 4-2 
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debugging external modules, 4-26 
example, 1-6 

execution control commands, 4-8 
execution history, 4-11, 4-20 
information commands, 4-17 
initialization of, 2-19 
overlaying of, 4-30 
stack commands, 4-20 
summary of commands, 4-31 
tracking commands, 4-11 
utility commands, 4-18 
declaration sections, interleaving of, 3-8 
delete procedure, 3-26 
example, 3-26 

deleting files, tee delete procedure 
DIAGS psect, 2-22 
Dijkstra, E.W., Info-1 
direct access, 2-10, 3-15 
dispose procedure, 2-24, 2-28, 3-30 
disposing of memory, 2-24 
donble compilation switch, 2-2, 2-18 
example, 1-8 

$double embedded switch, 2-5, 2-18 
double precision, 2-2, 2-5, 2-18 
colon notation, 2-2, 2-5 
example, 1-8 
dynamic link, 2-26 
Dynamic String Package, 2-18, 5-18 
and Sine lade directive, 5-18 
capabilities, 5-18 
example, 5-20 
library creation, 2-18 
procedures and functions, 5-19 
STRING, 5-18 
string declaration, 5-18 
string examples, 5-18 
use of, 5-20 


E 

EBNF syntax diagrams, 3-40 
notation, 3-38 
els processor switch, 2-4 
embedded switches ($), 2-4 
(check switch, 2-7 
(debug switch, 2-5 
(double switch, 2-5, 2-18 
examples, 2-4 
(indexcheck switch, 2-7 
(list switch, 2-6 
(aain switch, 2-5 
$no- reverses effect of <switcb>, 
tee <switcb> 

Ion switch, 2-5 
$paecall switch, 2-5 


$pointercheck switch, 2-7 
(profile switch, 2-6 
(raagecheck switch, 2-7 
(stackcheck switch, 2-7 
(standard switch, 2-6 
(Talkback switch, 2-5 
entry points, list of, 2-78 
p(gtln, 2-47 
support library, 2-19 
error correction, tee Debugger 
error handling, 2-39 
error messages, 1-2, 1-3 
compilation, 1-2, 2-61 
compiler, 2-76 
customized, 2-39 
run-time, 1-3, 2-35, 2-72 
error recovery, run-time, 3-14 
errors, 1-2 

compilation, 1-2 
compiler, 2-76 
fatal, 2-35 
I/O, 2-35 

run-time, 1-3, 2-35, 3-14 
run-time detection, 2-39 
errors compilation switch, 1-4, 2-1, 2-3 
error trapping, I/O errors, 2-37 
error walkback, 2-2, 2-5 
executable file, 1-1 
execution history, tee Debugger 
exltst procedure, 2-43 
declaration, 2-43 
status values, 2-43 
extended-instruction set, 2-4 
extended-range integers, tee unsigned in¬ 
tegers 

extended-range variables, 3-18 
Extended Backus-Naur Form, tee EBNF 
syntax diagrams 
extended precision, 2-2, 2-18 
extensions, default, 2-77 
I/O support, 3-14 
language, 3-8 
syntax, 3-8 

external directive, 2-11, 3-9 
external file access, 3-14 
external libraries, 2-14.4 
header file, 2-14.4 
external modules, 2-11, 3-8, 3-9 
and double precision, 2-18 
debugging of, 4-26 
definition, 2-11 
definition example, 2-11 
example program, 2-12 
FORTRAN routines, 2-11,2-14,2-14.2 
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global variable reference, 2-11 
identifiers, 2-11 
linking errors, 2-12 
MACRO routines, 2-11, 2-14 
$noaain embedded option, see em¬ 
bedded switches 

noaaln option, see compilation switches 
external procedures, 5-23 


P 


file, 1-1 

closing upon procedure exit, 2-44 

cross-reference, 5-13 

default extensions, 2-77 

executable, 1-1 

“header", 5-18 

input, 2-1 

listing, 1-4, 2-1 

object, 1-1 

output, 2-1 

overlay description, 4-30 
profile, 1-8, 4-32 
PROSE, 5-42 
source, 1-1 
statement map, 1-6 
symbol, 1-6 
temporary, 2-10 
text, 3-6, 3-30 
file buffer, 2-9 

default size, 2-9 
size of, 2-9 

file control switches, see I/O control switches 
file dump, example, 2-41 
file extensions, default, 2-77 
files, renaming of, 3-26 
fin processor switch, 2*4 
floating-point numbers, format of, 3-6 
outputting of, 3-17 
foreground operation, 2-49 
formatter, see PASMAT 
for statement, 3-30 

FORTRAN, called from Pascal, 2-11,2-14, 
2-14.2 

restrictions, 2-14.3 
forward directive, 2-12 
fpp processor switch, 2-3 
FRU1 command, 2-49 
function return value, 2-26 
structured types, 3-25 


getlia procedure, 2-46 
declaration, 2-47 
example, 2-49 
parameters, 2-47 
gefcpos procedure, 2-54, 3-16 
example, 2-55 
parameters, 2-54 

get procedure, 2-10, 3-15, 3-30, 3-31 
GLOBAL psect, 2-22 
/go I/O control switch, 2-0 
Grogono, Peter, 1-1, Info-1 
“grow* psects, 2-17 


H 


heap, 2-24, 2-27 

fragmentation of, 2-28 
free list, 2-17 
PlKORE, 2-28 
Hoare, C. A. R., Info-1 


I/O control switches, 2-9, 3-14 
/buff :n switch, 2-9 
examples, 2-9 
/go switch, 2-9 
/nfe switch, 2-9 
/odt switch, 2-9 
/nook switch, 2-10 
/size:n switch, 2-10 
/spaa switch, 2-10 
switch summary, 2-9 
/temp switch, 2-10 
I/O errors, 2-9 

trapping of, 2-9 
I/O error trapping, 2-37 
I/O functions, 2-50 

and standard Pascal, 2-50 
lazy I/O, 2-50 
I/O page, 2-25 
I/O support extensions, 3-14 
identifier, predefined, 3-32 
identifiers, extension to standard, 3-8 
naxlat, 3-6 
valid characters, 3-5 
flnclude directive, 2-19,2-40,2-44,3-8, 
5-18 

examples, 2-44 
syntax, 2-44, 3-8 
indent PB switch, 5-9 
index, tee alphabetize 
lindescheck embedded switch, 2-7,3-30 
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initializing the support library, 2*27 
initializing variables, 2*46 
input file, 2*1 

installation, compiler, tee Release Notes 
integer overflow, 3-31 
integers, range of values, 3-18 
unsigned, 2-57, 3-6, 3-18 
interrupt vectors, 2-23 
ioerror function, 2-37, 2-55 
instates function, 2-37, 2-38.2, 2-55 
ISO Standard Pascal, xiv, 3-1 
alternate symbols, 3-5 
implementation definitions, 3-6 
Pascal-2 extensions, 3-8 
recent changes, 3-1 


J K 

Jensen, Kathleen, 1-1, 3-1, Info-1 
Kernighan, Brian, Info-1 


L 

language extensions, 3-8 

structured constants, 3-9 
lazy I/O, 3-49 
Librarian, 2-18 
examples, 2-18 
libraries, run-time, 2-23 
support, 2-19 
system macro, 5-36 
LIIK command, 2-15 
example, 2-8 

Linker, 1-1, 1-15, tee alto overlays 
list compilation switch, 2-3 
example, 1-4 

$list embedded switch, 2-6 
listing, 1-4 
file, 1-4 

page heading, 1-4 
listing file, 2-1 
literal strings, 3-4 
LOAD command, 2-25 
look-ahead, 2-27 
loophole function, 3-31 
example, 3-22 


M 


MAC command, 5-37 
MACRO-11, tee PASMAC 
called from Pascal, 2-14 
MACRO assembler command, 2-3, 5-37 
■aero compilation switch, 2-3, 2-19 
macro package, tee PASMAC 


aain compilation switch, 2-2 
taaia embedded switch, 2-5 
manual, index, tee index 
manual purpose, xi 
aaxlnt identifier, 3-6, 3-30 
memory, typical arrangement, 2-27 
typical layout, 2-23 
memory allocation, 2-24 
user-defined types, 2-33 
memory map, 2-40 
example, 2-41 

memory usage, monitoring of, 2-27 
/M:n Linker option, 2-27 
■od function, 3-25, 3-30 
monitoring memory usage, 2-27 
multiple input files, 2-1 
multiple source files, 2-44 


N 

lovOK function, 2-27, 3-30 
sew procedure, 2-24, 2-27, 2-28, 3-30 
/nf a I/O control switch, 3-9 
ail pointer, 2-7 

no- reverses effect of <switeb>, tee <switcb> 
noioerror function, and /go switch, 2-9 
aoioerror procedure, 2-37 
non-standard features, 3-25 
program parameters, 3-25 
returning of structured types, 3-25 
nondecimal notation, 3-18 
nonpascal directive, 2-11, 2-14, 2-52, 

3-9 

null root segments, 2-17 


O 

object compilation switch, 2-3 
object file, 1-1 

object module libraries, tee Librarian 
Octal Debugging Technique (ODT), 2-9 
octal notation, 3-18 
octal output, 3-16 
/odt I/O control switch, 3-9 
examples, 2-10 
OPERROPAS, 2-39 
optimization, 2-59 

base address calculation, 2-60 
Boolean evaluations, 2-59 
constant folding, 2-59 
dead code elimination, 2-59 
expression targeting, 2-60 
redundant branching, 2-60 
redundant expressions, 2-60 
register assignments, 2-59 
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optloas PASMAT switch, 5-3 
Oregon Pascal Users Society (OPUS), Info-1 
Oregon Software, xl, 2-76 
Pascal Newsletter, Info-2 
Trouble Reports, 2-76 
organization, see manual, index 
origin declaration, 3-20 
examples, 3-20 
syntax, 3-20 
otherwiM clause, 3-13 
output specifications, 2-1 

colon notation, 2-2, 2-5, 2-18 
default field widths, 3-7 
octal notation, 3-16, 3-18 
scientific notation, 3-7, 3-17 
overlays, 2-16 

and getllft, 2-47 
Debugger, 4-30 
examples, 2-16 

extended memory, 2-16, 2-17 
load channel, 2-16 
low memory, 2-16 
null root segments, 2-17 
/0:n Linker switch, 2-16 
program segments, 2-16 
virtual, 2-16, 2-17, 2-27 
virtual job, 2-15 
ova compilation switch, 2-2, 3-8 
and GLOBAL psect, 2-22 
ton embedded switch, 2-5 


P 

PtAREi temporary storage, 2-47 
ipv directive, syntax, 3-9 
page procedure, 3-7 
parameters 

conformant array parameters, 3-2 
passing of, 2-26 
procedure and function, 3-2 
Pascal, Blaise, 1-2 
paecall compilation switch, 2-2 
tpaacall embedded switch, 2-5 
Pascal standard, xiv, tee alto ISO Standard 
Pascal 

Pascal Users’ Group, Info-2 
PASMAC, 2-14.1, 3-29, 5-23 

and system macro library, 5-36 

begin macro, 5-29 

command line, 5-25 

design of MACRO-11 procedures, 5-23 

eadpr macro, 5-30 

examples, 5-24, 5-33 

(unc macro, 5-27 

macro definitions, 5-24 


par an macro, 5-27 
placing in system macro library, 5-36 
predefined types, 5-31 
proc macro, 5-26 
purpose of, 5-23 
reave macro, 5-29 
save macro, 5-28 
var macro, 5-28 
PASMAT, 5-2 

command line, 5-3 
directives, 5-4 
examples, 1-4, 5-7 
limitations, 5-6 
optlona switch, 5-3 
portability mode, 5-5 
PB formatter, 5-9 

commit switch, 5-9 
example, 5-10 
formatting rules, 5-12 
indent switch, 5-9 
PlCODE psect, 2-22 
pldispoae procedure, 2-27, 2-28 
declaration of, 2-29 
example, 2-30 
parameters, 2-29 
PlDTlL psect, 2-22 
PlGBOV psect, 2-17 
PlGBVH psect, 2-17 

plgtln entry point, 2-47, tee alto getlin 
procedure 

pliaee function, 2-27, 2-28 
declaration of, 2-29 
example, 2-30 
parameters, 2-29 
PttOBE psect, 2-17 
PMA, 2-22, 2-40 

Ipointercheck embedded switch, 2-7, 
3-30 
pointers, 2-7 
nil, 3-30 
ail values, 2-7 
stack pointer, 5-27 
use of, 2-56 

Post-Mortem Analyzer (PMA), 2-22,2-40 
predefined functions and procedures, 3-26 
predefined identifiers, 3-32 
prod function, 3-30 

procedure walkback, 1-3, 2-2, 2-5, 2-35, 
tee alto walkback 
processor switches, 2-3 
ein, 2-4 
fin, 2-4 
fpp, 2-3 
sin, 2-4 
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PROCREF utility, 5-15 
command line, 5-15 
example, 5-16 
limitations, 5-16 

profile compilation switch, 2-3, 4-32 
example, 1-8 

(profile embedded switch, 2-6 
profile file, 1-8 
Profiler, 4-31 
example, 1-8 

execution requirements, 4-32 
output explanation, 4-33 
usage of, 4-32 
warnings, 4-36 
program heading, 3-8 
file parameters, 3-8 
program sections (“psects”), 1-21 
attributes, 2-22 
COISTS psect, 2-22 
DIAGS psect, 2-22 
GLOBAL psect, 2-22 
PlCODE psect, 2-22 
P$DYVL psect, 2-22 
P$GR0V psect, 2-17 
PSGR1H psect, 2-17 
P$K0RE psect, 2-17 
SHIFTS psect, 2-22 
TABLES psect, 2-22 

program segments, and overlays, 2-16 
PROSE, 5-20, 5-38 

basic text units, 5-39 
command line, 5-42 
directive format, 5-40 
directive summary, 5-63 
examples, 5-41, 5-52, 5-57 
index directives, 5-54 
input control directives, 5-43 
“keep” buffer, 5-52 
miscellaneous options, 5-44 
output control directives, 5-55 
page control directives, 5-47, 5-48 
paragraphs, 5-49 
parameter values, 5-40 
title directives, 5-47 
psects, nee program sections 
purpose of manual, xi 
put procedure, 2-10, 3-15, 3-31 

R 

random access, 3-15, 2-10, see also getpos 
and setpos procedures 
simulated, 2-54, 3-16 
(rangecheck embedded switch, 2-7,3-30 
reading command lines, 2-46 


readlu procedure, 3-16, 3-30 
read procedure, 3-16, 3-30 
real numbers, 2-18 
format of, 3-6 
outputting of, 3-17 
recursion, 2-36 
ref function, 3-31 
registers, 2-26 

saving of, 5-28 
renaae procedure, 3-3S 
example, 3-26 

renaming files, nee renaae procedure 
reserved words, 3-32 
reset procedure, 2-9, 2-38, 3-7, 3-14, 
3-26, 3-30 
parameters, 3-14 
syntax, 3-14 
return link, 2-26 

rewrite procedure, 2-9, 2-38, 3-7, 3-14 
and size:n I/O control switch, 2-10 
parameters, 3-14 
syntax, 3-14 
round function, 2-58 
R PASCAL command, 2-1 
run-time error messages, 2-72 
run-time error reporting, customizing of, 
2-39 

OPERRO.PAS, 2-39 
UERROR.PAS, 2-39 
run-time errors, 1-3, 2-35 
procedure walkback, 1-3 
recovery from, 3-14 
walkback, 1-3, 2-35 
run-time library, 2-23 
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•ay err procedure, 2-37, 2-38.1, 2-40 
example, 2-38.2 
scientific notation, 3-7, 3-17 
/seek I/O control switch, 2-10, 3-15, 
3-16, 3-31 
example, 3-16 

seek on text files, examples, 2-55 
simulated, 2-54 

seek procedure, 2-10, 2-54, 3-15 
segments, and overlays, 2-16 
setpos procedure, 2-54, 2-55, 3-16 
example, 2-55 
parameters, 2-55 
sets, 3-8, 3-31 
use of, 5-20 

.SETTOP system directive, 2-27 

SHIFTS psect, 2-22 

sla processor switch, 2-4, 2-22 
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single-character mode, 2-9 
single precision, 2-5, 2-18 
size function, 2-30, 2-34, S-tl 
/•izn:n I/O control switch, 1-10 
source, 1-1 
file, 1-1 
program, 1-1 

source file concatenation, 1-13, 5-18 
source program, 1-1 
•pace function, 2-27, 1-18 
data types, 2-28 
declaration of, 2-28 
example, 2-30 

/•pan I/O control switch, 1-10 
stack, 2-19, 2-27, 5-23 
contents, 2-24 
default size, 2-27 
reserving space, 2-30 
tpacn function, 2-28 
stack frame, 2-25 

Istackcheck embedded switch, 2-7 
stack frame, 1-18 
stack pointer, 2-17, 2-24, 5-27 
standard, tee ISO Standard Pascal 
standard compilation switch, 2-3 
(standard embedded switch, 2-6 
standard Pascal, xiv, tee alto ISO Standard 
Pascal 

START.OBJ, and virtual overlays, 2-17 
statement map file, 1-6 
storage allocation, 2-33 
pre-defined types, 2-33 
size and bltslze, 2-34 
user-defined types, 2-33 
Btring processing, 5-18 
strings, tee Dynamic String Package 
declaration of, 3-16, 5-18 
examples, 5-18 
literal, 3-4 

structure, manual, tee organization 
structured constants, 3-9 
examples, 3-10 
multidimensional arrays, 3-12 
style notes, xvi 
nncc function, 3-30 
support library, 2-19 

data definitions, 2-19 
entry points, 2-19, 2-78 
error-control module, 2-39 
initialization procedure, 2-27 
initializing of, 2-19 
LIBDEF.PAS, 2-19 
library work area, 2-19 
switches, 2-2,2-4,2-18, tee alto I/O con¬ 


trol switches, compilation switches, 
embedded switches, processor switches 
compilation, 2-2 
compilation examples, 2-7 
embedded ($), 2-4 
I/O control, 2-9 
processor, 2-3 
symbol file, 1-6 

syntax diagrams, Pascal-2, 3-33 
system device (ST:), 2-15, 2-46 
system macro library, and PASMAC, 5-36 


T 

TABLES psect, 2-22 
/trap I/O control switch, 3-10 
termination status, tee raitnt procedure 
teat compilation switch, 2-3 
text files, 3-6 

text formatting, tee PROSE 
Thomas, Rebecca, Info-1 
tiJM function, 3-37 
example, 3-27 

tiaes compilation switch, 2-3, 2-46 
tlanstup procedure, 3-28 
example, 3-28 
parameters, 3-28 

traceback, tee walkback, procedure 
Trouble Reports, 2-76 
true function, 2-58 
two’s complement arithmetic, 2-57 
type checking, suppression (loophole), 
3-21 

type coersion, tee loophole function 
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UERRORPAS, 2-39 

Of loat procedure, unsigned floating-point 
conversion, 2-57 

unsigned integers, 2-28, 8-87, 3-6, 3-18 
floating-point conversion, 2-57 
outputting of, 2-57 
subrange notation, 2-57 
user service routine (USR), 2-25 
utility package, 8-1 

Dynamic String Package, 5-18 
PASMAC, 2-14.1, 3-9, 8-33 
PASMAT, 3-9, 5-2 
PB formatter, 5-9 
PROCREF, 5-15 
PROSE, 5-38 
XREF, 5-13 

Otruc function, unsigned truncation, 2-58 
Owrite procedure, unsigned write, 2-57 
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variable initialization, 2*46 
VIRJOB.OBJ, 2-15 
virtual job, example, 2-17 
START.OBJ, 2-17 
VIRJOB.OBJ, 2-15 
virtual jobs, 1-15 

job status word (JSW), 2-15 
virtual overlays, 2-27, $ee alto overlays,extended 
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walkback, xiv, 2-35, 3-15 
disabling of, 2-35 
examples, 2-36 
procedure, 1-3, 2-2, 2-35 
psect, 2-22 
run-time, 2-35 

talkback compilation switch, 2-2 
(talkback embedded switch, 2-5 
Wirth, Niklaus, 3-38, Info-1 
K: logical device, 2-46 
work files, example assignment, 2-46 
location of (IK:), 2-46 
torktpace compilation switch, 2-2 
tritela procedure, 3-4 
trite procedure, 3-4 
trite statement, double-precision values, 
2-2 
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XM monitor, virtual jobs, 2-15 
XREF utility, 5-13 

command line, 5-13 
example, 5-14 
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Documentation Evaluation Report 


Pucil-I VJ.1 User Manual Update Package No. t 
PDP-11/RT-I1 


Good documentation is as important as good software. We at Oregon Software are well aware that 
you expect both, so we value your responses. Use this form to write down comments and suggestions, 
which will help us improve the quality and usefulness of our publications. If you require a written 
response, submit your comments on a Trouble Report. 


Rate the following items on a scale of 1 to 5, with 5 being the highest rating. 

— Initial impression -Ease of fading information 

-Organisation -Accuracy 

-Ease of reading -Ease of updating the manual 

What changes in the documentation, in your opinion, are most useful?_ 


What aspects of the update package need improvement? 


What errors have you found in this update package? Include page numbers. 


Name -- Site # 

Company __ Date 
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Mailing Instructions 


Domestic. After filling out the report, cut along the vertical dotted line to remove the punched 
holes. Then fold this page so these instructions are hidden and the BUSINESS REPLY MAIL permit 
faces out. Secure the loose fold with staple or tape, then mail. 

International. Please enclose this page in an envelope and return it to jour distributor. If you do 
not have a distributor, return the report directly to us. (Unfortunately, we cannot supply prepaid 
postage for overseas respondents.) 

Thank you in advance for your response. 



UNITED STATES 


BUSINESS REPLY MAIL 

FIRST CLASS PERMIT NO. AMI PORTLAND.OR. 


POSTAGE WILL RE PAID BY ADDRESSEE 


OREGON SOFTWARE, INC. 
Attn: Documentation Comments 
6915 SW Macadam 
Portland, OR 97213 





























Release Package Checklist 


SOFTWARE* Pascal—2 Development System 
VERSION* VS.1D 
OPERATING SYSTEM* RT-1I 
DATE OF RELEASE* January IS, 198 S 


This release package contains the following marked items. If a discrepancy exists between the marked 
items and the contents of your release package, please contact Oregon Software at (503) 245-2202 
immediate^. 


Pascal-2 software on: 

□ Magnetic tape. □ 800 bpi □ 1600 bpi 
Floppy disk. 

□ Cartridge disk. 

Pasc&l-2 User Manual, Second Edition. 

^Documentation Update Package, Update No. 2. 

S. Release Notes, including the Installation Guide. 

ST Standard Pascal User Reference Manual by Doug Cooper. 
^ Programming in Pascal by Peter Grogono. 

An assortment of Pascal Newsletters. 

Extra Trouble Report forms. 

□ Extra “Request to Amend” forms. 

□ License agreement. 
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Pascal-2 V2.1D/RT-11 Release Notes 


The information contained in this document describes the Pascal-2 V2.1D release package. In these 
notes you will find: 

• A list of problems (“bugs") we’ve fixed in this release. 

e Notes on changes in the documentation and on how to update the user manual, 
e Miscellaneous notes of interest to Pascal-2 users, 
e The Installation Guide. 

These release notes should be read before attempting to install the compiler and utilities on your 
system. The “Documentation Notes" section of the release notes should be read before attempting 
to insert the change pages from the update package into the user manual. 


Style Notes 

This document follows these style conventions: 

Text: 

Pascal reserved words, predefined symbols, switches and compiler directives are in boldface 
typewriter: begin, vrlte, (Include, aonaln. Portions of examples referred to in the 
text appear in boldface typewriter (the type style used in examples). Program, system 
and file names are in upper-case letters in the same type style as the text* SAMPL 
VMS, SAMPL.PAS. 

Program Examples: 

Commands that you should enter are in underlined boldface typewriter: 801 EX These 
commands assume a carriage return at the end. 

Program Listings: 

The Pascal—2 compiler accepts any combination of upper-case and lower-case characters. 
Examples in this manual have Pascal words in lower case and have user-defined words 
with an initial capital letter and other capitalization as needed for readability, as shown 
in this program fragment: 

procedure Shoe; 
begin 

SoaeOserictlon; 
vrltela(Benult); 

•»d; 


Terminology: 

We use standard terms as they are used in documents describing the RT-11 operating 
system. 
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Changes in the Software 

Version 2. ID is primarily » maintenance up-date; changes in software between Versions 2.ID and 
2.1C consist for the most part of fixes for previously known problems. 

Problems We’ve Fixed 

Version 2. ID corrects the following problems: 

Record field es • parameter 

The compiler generated bad code when certain nested record fields were passed as a parameter. 
Negative stack offset for common subexpressions 

Depending upon the location of a variable’s declaration, two identical calculations involving certain 
functions, including sin and cos, could have different results. The library routines for the functions 
caused the compiler to reference a negative offset from the stack pointer. 

Wrong results from Integer comparison 

A comparison between an integer and a subrange that is an element of a packed record produced 
an incorrect result. 

Incorrectly addressed real variable 

Certain globally allocated real variables were incorrectly addressed. As a work-around, reducing the 
size of the program seems to remove the error. 

Dynamic string package errors 

The Insert routine printed the error message Array subscript out of bounds when the com¬ 
bined length of the two input strings exceeded the target string's length. Now, the insert string is 
concatentated onto the end of the target string and truncated. 

The Concatenate routine reported errors when the string to be concatenated overflowed the target 
string. The input string is now truncated to fit. 

%Page directive didn't work 

On listings, (page incremented the page number incorrectly. 

Reserved Instruction trap error 

Using a packed record containing integers in a nested procedure call caused a reserved instruction 
trap. 

Illegal instruction gave "compiler writer error* 

Using certain illegal instructions resulted in the error message for internal problems instead of the 
appropriate error message. 

No error message 

The compiler failed to give an error message for attempts to pass an element of a packed structure 
as a variable-parameter. 


2 














Problems WsV* Fixed 


The compiler Incorrectly n e ed RO for procedure cells 

The compiler failed to save the contents of the BO register after aoapascal procedure calls. 
Memory protection Tloletlon 

A memory protection violation occurred in isolated instances when the value of BO was not initialized 
before adding the offset. 

Sets generated bad code 

Set constructor expressions of the form [varl..var2] generated bad code at times. 

Set type produces wrong result* 

The declaration and statement 

typo a > sot of (oao.tvo.throo); 
var b:a; 

begin 

b:» [one,throe]; 
write(b c [] <» []); 

and. 

produced a set of 256 items merged with a set of 3 results. 

Function returns Incorrect result 

The compiler incorrectly changed bit lenghts to byte lengths when a function returned a structured 
type. 

Bit optimisations Ineorrsct 

Compiler optimization of certain user-deBned procedure calls produced an incorrect sequence of 
execution. 

PB formatter reject* "nonpaaeal” 

The formatter failed to recognize the aoapascal directive. It now treats nonpascal exactly like the 
external directive. 

String comparison range wrong 

For string comparisons, ord(char) was in the range 0. .265 instead of -128.. 127. The range is now 
correct. 

Unsigned characters treated as signed 

The compiler treated 8-bit characters as if they were signed numbers when the character was 
optimized. 

Assignment statements caused fell ore 

A complicated series of assignment statements involving arrays of type real previously failed. 

Compiler consistency checks reported 

Certain instances of undeleted tenps la procedure... were fixed in 2.1D. 
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Llaki|t filloN daring installation 

A missing continuation character in the file UTILS .XM, which bnilds the ntilities, cansed a failure 
at the point where XREF is linked. 

Misleading error meeange for nonexistent files 

The compiler printed the error message “Unknown Pascal run-time error” for an attempt to compile 
a nonexistent file or a file containing a finclads of a nonexistent file. 

Debugger overlays do not work for XM monitor systems 

XMDBG.COM, the XM monitor command file that links Debugger modules with a Pascal program, 
now correctly overlays Debugger modules. 
















Problems We Vo Fixed 


Documentation Notes 

The documentation for Pascal-2 Version 2.1D includes the second edition of the Pascal-2 User 
Mutual, which documents the enhanced V2.1 software, and Update Package No. 2, documenting the 
2. ID features. (Update Package No. 1 was previously distributed and all changes then noted have 
been incorporated into the manual.) We have expanded a number of sections, including “External 
Modules," “Resident and Cluster Libraries,” and “The Debugger Guide.” The expanded sections 
provide new information and clarify and correct earlier material, at user suggestion. Update Package 
No. 2, records these changes and is made up of “change pages” for insertion into the user manual 
at the appropriate place. The update package’s cover sheet should be inserted into the manual just 
before the first contents page, to keep a history of changes to the manual. 

The Release Notes, containing the Installation Guide, is a companion document of the Pascal-2 User 
Manual and should be kept with that manual for reference. 


Miscellaneous Notes 


Offleiml ISO Standard for Pascal 

The Pascal language now officially has an international standard. The International Standards 
Organization, in a vote tallied this summer, adopted a standard language definition for Pascal. The 
action followed earlier adoption of an American standard that is a subset of the international one 
lacking only conformant array parameters. 

The sequence leading to adoption of the Pascal standard began in December 1982, when ANSI and 
IEEE agreed on the American standard, identical to the international draft standard except for 
conformant array parameters. At the same time, the Joint Pascal Committee of ANSI and nrere 
recommended adoption of the international standard Level 1 (including conformant array parame¬ 
ters) to the U.S. committee known as X3J9, which then voted "yes” on the international standard 
at the next meeting. Previously, the U.S. was one of three “no” votes. This time, the ISO standard 
passed with no dissenting votes and one abstention. 

Peppered throughout the Language Specification of the user manual are references to the “draft* 
standard. The word “draft" can be ignored. (Change pages were not issued for this change.) 


Packing Problems 

Several users have uncovered bugs in Pnscal~2’s packing of records and arrays. We believe that it 
may be necessary to modify the packing algorithm slightly in version 2.1E in order to correct these 
problems. If such a change is necessary, users who have programs that involve the reading and 
writing of packed records or arrays may have to convert their data files to the new format in order 
to use V2.1E. This new version will be released in roughly six months; if the packing conversion 
is necessary we will make every effort to dearly document when and how to follow the conversion 
process. 


Stack Overflows 

Especially large stack overflows, those that extend beyond the heap and into the program code 
sections of memory, have the potential for causing serious problems. In some cases it is possible for 
the error to prevent the appropriate error message from being printed or the program from properly 
terminating. In some rare instances, the condition can even lead to the disruption of the computer’s 
operating system. It is the programmer’s responsibility to avoid such excessively large overflows by 
controlling the size of local variables and value parameters passed to procedures. 
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EXITST Crsstss s Walkbnek for ‘Suvuro Error* Status (4) 

The Exltst procedure ■ a support library routine that sets the termination status of a program 
and stops the program when a “severe error” status is detected. The procedure’s integer argument 
determines the termination status for any program that calls it. When a “severe error” status of 4 
is passed, the procedure also invokes the post mortem analyser to create a walkback of the program 
execution from the point of failure. 














Pascal-2 V2.1D/RT-11 Installation Guide 


raw o^n'vJ'I.d'vr' *° k, * d ,b ‘ RT - U P “ c **- J »■ ro.. V .Um. The V2.1 eoft.ue 

To install Pascal-2 V2.1 for RT-11, follow the step* below: 

1. Copy all of the Pascal-2 files to the system device (ST:); 

2. Select a compiler depending on your system monitor; 

3. Select a run-time library depending on your processor hardware options; 

4. Compile the Pascal-2 utility programs; 

5. Set the compiler’s listing file page sise to a value other than M octal (optional); 

6. Extract the Debugger modules from the support library for use in overlaying the Debuuer 

against user programs. * 


7. Delete files no longer needed (optional). See Appendix B for a sample deletion command. 



- r - 0 wvrivwsMV. v/|SUa BUCCCMU1 COHipieilOQ 0 

system is fully operational as described in the Pascal-2 User Manual. 



Copying the Pascal-2 Files to the System Device 

Copy aU of the distribution files to the system device (ST:) using the ASSICI and COPT commands 

M ahnwfi heUwf ’ 


■ ASSICI ST DK 

.COPT MTO: ST: 


— assigns ST: as default device 
copies magtape to system device 


If your system disk is a floppy disk, or is otherwise limited in available space, you should first read 
the following sections and select the files that are necessary for your system. Then copy those files 
to your system. The minimal system requires one compiler file and one library file. You may wish to 
build more than one system disk and, for example, install the compiler, library, and Debugger on 
one disk and the utility programs on a second system disk. 


Selecting a Compiler for Your System Monitor 

T , h " e two compilers supplied with Pascal-2. Your choice of a compiler depends on the version 
of the RT-11 monitor you intend to use. There are four possibilities: the Base-Line (BL) monitor 
the Single- J ob (SJ) monitor, the Foreground-Background (FB) monitor, and the eXtended-Memory 
(XM) monitor. 

If you are using either the BL or the S J monitor, choose the compiler called S J.SAV. If you use the 
XM monitor, select the compiler called XM.SAV. 

T i. he JE? monitor doe# not efficient memory to run the Pascal-2 compiler. If you are using 
the FB monitor, you must switch to either the S J or XM monitor (using the BOOT command) before 
compiling a Pascal program. Once compiled, programs may be linked and run under the FB monitor. 
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The XM compiler should be chose, over the S J compiler where po«ible because it use. the extended 
memory or “virtual* overlay capability and gives faster compilations. 

When you have selected a compiler file, copy H to ST:PASCAL.SIT with the following command, 
which assumes the default device is ST:. 

t sj SAT PASCAL. SAT. ---- install. SJ compiler 

rnpy TV SAT FISCAL . SAT - --- installs XM compiler 


You may then delete S J.SAV and XM.SAV, or you may leave them on your system disk for use under 
their respective monitors. (See Appendix B.) 


Selecting a Run-Time Library 

There are four run-time libraries supplied with Pascal-2, one for each combination of proceswr 
instruction sets. Choose the library that matches the configuration of the processor that will run 

your compiled programs. 

The possible configurations are: 

tod . nnvMior with the Floating Point Processor instruction set. The FPP is standard 

• equipment on the PDP-11/60 and optional on aU new PDP-ll’s and the LSH1/23. If your 
processor include, the FPP, select the LIBFPP.OBJ library. 

. FIS - the Floating Instruction Set. The FIS hardware is an 

LSI-11/2 and some older PDP-11 processors. If your processor has FIS, select the LIBFIS.OBJ 

library. 

• EIS — Extended Instruction Set, for hardware support of multiply, divide, and long shift 
SLJoL EIS » ata.dard otpripment .. H «- PDP-11 and LS H ‘/23 pr~^«.n. «d «. 
option available to, all older LSl-ll'e and PDP-ll'a. It Jton, proeomor baa neither FPP nor FIS. 
but does have EIS, then select the LIBEIS.OBJ library. 

• For orocessors with no extended or floating instructions, select the LIBSIM.OBJ library. This 
library operates on any LSI-11 or PDP-11 regardless of its actual configuration, but does not 
take advantage of any optional hardware. 

... o. cr-P ascal OBJ with the following command or one similar 

foT deiSgVn th^processor configuration. In the command, ST: is the default^device. 
mpr l.tnrpp.OBJ PiSClL. m -FPP library 

Yon nt, then remove the other librnjr ale., or have them on the .yrtem for nte with other 
configurations. (See Appendix B.) 


Compiling the Utility Programs 

Five Pascal-2 utility programs are supplied in source form and are automatically compiled and linked 
[l *ne of ^wo command files, UTELS.SJ and UTILS .XM. UTILS.SJ prepares the utility Programsfor 
execution under the SJ, FB and BL monitors; UTILSJCM prepares them for execution under XM. 
Feel free to examine these command files before executing it indirectly using one of two commands. 

tPTILS.SJ 

or: 

noms.HI 
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Compiling tho Utility Programs 


Upoa completion of UTILS, the utility programs are available for use as described in the Utilities 
Guide of the Paacat-2 User Manual. 

In UTILS JCM all of the utilities must be linked as "virtual jobs” made up of virtual overlays because 
their load images are larger than 16K. (The XM monitor can not load a program with a root segment 
larger than 16K.) The Pascal-2 file START.OBJ is used in the link process to create a null root 
segment, tricking the Linker into loading the oversised program. The Paaeal-2 User Manual contains 
a detailed description of this technique for user programs in Pascal. 

When UTILS completes, you may then delete the extra .OBJ and .MAP files left on the disk bv the 
UTILS command file. (See Appendix B.) 7 


Setting the Page Size of the Compiler’s Listing File 


The command files RTPAGE.COM and XMPAGE.COM, supplied with the Pascal-2 release, provide 
a means for changing the number of lines per page of the SJ and XM compilers’ listing file, 
respectively. This feature allows for the use of odd-sized printer paper or for special printing needs. 

Before executing either command file, you must modify the lines-per-page value in the fifth line of 
data in the command file. (The first line of data is the file to patch.) The normal page size (in octal) 
is 66, not counting header lines. ' 

I Conaad file to patch tho SJ version of Pascal to change 
I the lines per page of a listing file 
I 

I Change the auaber nn (octal) to another value, la octal 
! that represents the auaber of lines per page of a listing filo 

1 that you require. 

! 

R SIPP 
ST:PASCAL 

3075 

2 

” ----lines per page 

*C 

where ns is the desired page size in octal. The value ‘3075’ is the base address of the symbol PACELI, 
and the actual value in the supplied command filemay be different. The value ‘2’ is the byte offset 

from the base address of the location to patch. Values for the page size and byte offset must not be 
changed. 

After editing the appropriate file, execute it indirectly with the command: 

fi B If A QE ' —- for SJ installation 

or: 

*«n« 


for XM installation 
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Extracting Support Library Modules for Debugger Overlays 

Before users caa overlay the Debugger against their programs, the command file EXTRAC.COM 
must be executed. This command file, supplied with the release kit, extracts from the Pascal support 
library the Debugger and other key modules used by the XMDBG.COM (for XM systems) and 
SJDBG.COM (for SJ systems) command files, also in the release kit. (Users can then execute either 
XMDBG.COM or SJDBG.COM to overlay the Debugger and their Pascal programs.) EXTRAC.COM 
places the modules onto the system device (ST:), with the extension J)BG. It need only be executed 
once. 

The command file can be executed with the indirect (at-sign) processor, as shown: 

•ETTRAC 


Installing Pascal-2 With Pascal-1 

The Pascal-1 system compiler can be renamed to allow simultaneous use of Pascal-1 and Pascal-2. 
Then, the files for both systems can be present on the system device without conflict, provided that 
the compiler/library versions and upgrade levels are themselves compatible. (For example, Pascal-1 
V1.2K is compatible with Pascal-2 V2.0K, and V1.3C is compatible with V2.1C; V1.2K, however, 
is not compatible with V1.3C. 

The object library PASCAL.OBJ can be shared by the two systems (as long as the two system 
versions are compatible); the libraries supplied with Pascal-2 include all of the Pascal-1 routines. 
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Appendix A: Distribution Files 


Compilers 

SJ SAT 

Pascal-2 Compiler for SJ monitor 

XX .SAT 

Pascal-2 Compiler for XM monitor 

Object Libraries 

LIBFPP. OBJ 

Library for processors with FPP and EIS 

LIBFIS.OBJ 

Library for processors with FIS and EIS 

LIBEIS. OBJ 

Library for processors with EIS only 

LIBSIM.OBJ 

Library for base-level processors 

TIBJOB.OBJ 

Header module for XM virtual jobs 

STABT .OBJ 

Nall root module for XM virtual overlays 

Command Files 

EXTBAC.COM 

Support library module extractor for Debugger overlays 

SJDBG .COM 

Debugger overlayer for SJ monitor 

XMDBO .COM 

Debugger overlayer for XM monitor 

RTPACE.COM 

SJ listing-file page size patcher 

XMPAGE.COM 

XM listing-file page sixe patcher 

UTILS .SJ 

SJ, F8 and BL utility installer 

UTILS .XM 

XM utility installer 

Utility Programs 

PASMAT.PAS 

Program formatter 

PB .PAS 

Pascal Beautifier 

XBEF .PAS 

Croes-referencer 

PROCRE.PAS 

Procedure cross-referencer 

PROSE .PAS 

Text formatter 

STRUG .PAS 

String package 

PASMAC.MAC 

MACRO-11 interface package 

SAYERB.PAS 

System error message printer 

UERROB.PAS 

User error reporting module 

OPERRO.PAS 

Support library error routine 

LIBDEF. PAS 

Support library definitions 

CSITTP.PAS 

Command String Interpreter (CSI) typo definitions 

CSIPRO.PAS 

CSI procedure definitons 

FIXABG.PAS 

CSI argument parser 

FIXIK.PAS 

CSI {include file handler 

FIXOUT.PAS 

CSI temporary output manager 

STMDCL.PAS 

CSI symbol table declarations 

STMCOO.PAS 

CSI symbol table manager 

CITIUM.PAS 

CSI command-line number converter 


Demonstration Programs 

* Vary from release to release 


Installs 
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Appendix B: Typical XM Installation 


The following steps illustrate the installation of Pascal-2 from magtape on a processor that includes 
the FPP floating point processor. The Pascal-2 compiler for the extended memory (XM) monitor is 
selected. 


. ASSIC1 ST DK 


assigns ST: as the default device 


• CQFT MTQ: Si! 

COPT LIBFPP -OBJ PASCAL.OBJ 
COPT PI.SAT PASCAL.SIT — 

iOTlLS.m - 

R PASCAL -- 

PASMAT/TIME/T0RESPACE=85O 


■ selects the FPP library 
selects the XM compiler 

-builds the utilities 

-builds PASMAT 


I Tbs following link will round up feka root to 4K and put tko extra 


! nsaory on tho heap 

b Lin 

PASMAT,PASMAT*STABT.TIBJOB/0:30000// 
PASMAT.PASCAL/?:1 


// 

PIGBOT 


*C 

B PASCAL -—-—-builds PB 

PB/TIME 
B LIU 

PB.PB*STRAT.TIBJOB/T:20000// 

PB,PASCAL 

//PIGBOT 

*C 

B PASCAL I. builds XREF 

ZBEF/TIVE 

b Lin 

XREF 3 STABT.TIBJOB/U:20000// 

XREF,PASCAL/T:1 

// 

PIGBOT 


*C 

B PASCAL — builds PROCREF 

PBOCBE/TIME 
B LIH 

PBOCBE,PROCRE=STABT.TIBJOB/D:20000// 

PROCREF,PASCAL/T:1 

// 

PIGBOT 

*C 

B PASCAL ——————————builds PROSE 

PBOSE/TIME/10RISPACE=700 

B Lin 

PROSE,PBOSE=STABT.TIBJOB/O:20000// 

PROSE.PASCAL/T:1 

// 

PIGBOT 

*C 


Install'd 


























Appendix Bi Typical XM Installation 


■TWICE 
. 0EITR1C 


seU listing page sise to value other than 66 octal (optional) 
—— extracts library modules for Debugger overlaying 


R PI? --- 

»SJ■SAT.IM.SIT/D - 

♦LI BFfPiQBJ.LlBFIS.OBJ.LIBEIS.OBJ.LIBSnt.QlJ/P 

♦P ASHAT.OBJ.PB.OBJ.PEP■OBJ.PROCRE.OBJ.PROSE.OBJ/P 
<PASm i,mP.PB,mP.IBEP.MiP.PBQCBE.liiP.ranSE MIE/P 


cleans up the system disk (optional) 
Remove the compilers, leaving PASCAL.SAV 





















DISTRIBUTOR CUSTOMERS 


Please submit all technical support questions, verbal or written, 
directly to your authorized Oregon Software Distributor. 

When you have a problem, please contact your Distributor by 
telephone. If the problem cannot be solved over the telephone, 
we request that you submit a written Trouble Report. 

When submitting a written report, please complete one of the 
enclosed Trouble Report Forms and send it to your Distributor 
along with a small sample program demonstrating the problem you 
are experiencing. If you cannot reduce the problem to a one—page 
sample program. Submit your Trouble Report with the program on a 
single density floppy disk (preferably RT-11 format) or on a 

magtape. Your Distributor will then duplicate the problem at his 
facility. 

In most cases your Distributor will be able to answer your 
questions. If necessary, your Distributor will forward your 
written report to Oregon Software for a solution. We will do 
everything possible to respond to your problem within 30 days 
after the report is received at Oregon Software. Once a solution 
is reached, it will be forwarded to your Distributor who will then 
contact you. 

Thank you for support and interest in Oregon Software products. 


Oregon 

Software 



















/> 
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■ ■■■ '■ INSTRUCTIONS 

Check recent issues of our Pascal Newsletter to see whether the trouble has been reported. The News¬ 
letter may describe a quick fix or tell you that the problem has been fixed in the current release. If so, 
your Designated Contact Person should request an update in writing. If our Newsletter and manuals 
dont help, complete the front of this Trouble Report and send it to Oregon Software. A few suggestions: 


Your Name: We'll call or write you if we need more details about the problem. 

Designated Contact Person: The "responsible official" for our software at your site, usually the senior 
programmer. We'll send the DCP a copy of the correspondence about this problem. 

License Number: The serial number of your site printed in the headline of all program listings. Looks 
like "1-876." 

Some problems relate to specific combinations of hardware, software, and processors. We need to know 
your setup: 


Processor Model: The processor line and specific model number ( not the serial number!). 
Examples: PDP-11144, 256 KB • LSI-11123, 56 KB • VAX-111750, 768 KB. 


Processor Options: Any installed processor options that extend the instruction set. EIS = Extended 
Instruction Set. FIS = Floating Instruction Set. FPP = Floating-Point Processor. FPA = Floating-Point 
Accelerator. 

Operating System and Version: The software operating environment. Please, please, include the 
specific version! Examples: RT-11 V4XM • RSX-UM-Plus V3.2 • RSTSlE VTA • VMS V2.1 

Problem Description: Reduce the problem to the simplest situation in which it occurs. One page is the 
largest program we can reasonably type by hand. If a larger amount of code is needed to demonstrate 
the error, send us a magtape or single density floppy. Unfortunately, we cannot return these. Note any 
intuitions you have about possible causes of the trouble. Remember: WE MUST BE ABLE TO 
REPRODUCE THE TROUBLE HERE. 


OUR RESPONSE 


^ It's already fixed or Fixed in next release. 

You will automatically receive a copy of a release in which the problem is fixed, if your Designated 
Contact Person has signed the Conditional Update Request on the front of this form. 

Maybe a bug, but... 

Documentation problems, customer errors, obscure "features" or inherent limitations in our 
implementation can each cause trouble. We will help you work around the problem and/or 
supplement our documentation in these cases. Please understand that our support is limited to 
correcting problems with our software and does not include applications programming. 

In any case — 

We will send you a written response within a month. 

















Trouble Report 

See instructions on reverse side. 

CUSTOMER IDENTIFICATION 


Your Name__ Designated Contact Person (if different) 


Conditional Update Request: If the Trouble Report pertains to a problem that has been fixed or will be fixed in the next release, this signature constitutes a request for an 
update which Oregon Software will provide under the terms of the existing software license and/or support agreements. 




Date - 

/ 

/ 

signature__ _ — --- 

License Number --- — - - 

^unipcuiy-—- 


Date Submitted 

/ 

/ 

Address__ _ 


Telephone ( ) 


ext. -— 



Qrara CountrV 

Zip/Postal Code 


City --- — - 

~ . . . i Prnroccnr Onrinn^ IF.TS FIS. FPP FPA. etC.)_— - — ---—-——————— 

processor Moaei -- 

V, 




distribution Medium 

Software and Version 


Operating System and Version --- 




PROBLEM DESCRIPTION 

( ) Major Problem ( ) Minor Problem ( ) Suggestion ( ) Inquiry 

If the problem could have been avoided by better documentation, explain below, 
f the problem is intermittent, outline below the conditions under which the problem seems to occur. 

Describe the problem (use additional sheets if necessary): 




— 



FOR 


Log Number-—- ™ e - 

>ate Assigned__/-/- Problem Type- 

Assigned to-—-— - 

Date of Response to Customer-/-/- Summary of Action 

( ) Circulate - 




Oregon 

Software 

6915 S.W. Macadam Avenue 
Portland, Oregon 97201, USA 
503/245-2202 
TWX: 910-464-4779 


rnnvriaht® 1981 Oreaon Software. Printed in USA May 1981 


OS-116 
























































INSTRUCTIONS 


Check recent issues of our Pascal Newsletter to see whether the trouble has been reported.The News¬ 
letter may describe a quick fix or tell you that the problem has been fixed in the current release. If so, 
your Designated Cor-lact Person should request an update in writing. If our Newsletter and manuals 
dont help, complete the front of this Trimble Report and send it to Oregon Software. A few suggestions: 

Your Name: We'll call or write you if we need more details about the problem. 

Designated Contact Person: The "responsible official" for our software at your site, usually the senior 
programmer. We'll send the DCP a copy of the correspondence about this problem. 

License Number: The serial number of your site printed in the headline of all program listinqs Looks 
like "1-876." 

Some problems relate to specific combinations of hardware, software, and processors. We need to know 
your setup: 

Processor Model: The processor line and specific model number ( not the serial number!). 

^ Examples: PDP-11144, 256 KB • LSI-11123, 56 KB • VAX-111750, 768 KB. 

Processor Options: Any installed processor options that extend the instruction set. EIS = Extended 
Instruction Set. FIS = Floating Instruction Set. FPP = Floating-Point Processor. FPA = Floating-Point 
Accelerator. 

Operating Sy tem and Version: The software operating environment. Please, please, include the 
specific version! Examples: RT-11V4XM • RSX-llM-Plus V3.2 • RSTS/EV7A • VMS V2.1 

Pioblem Description: Reduce the problem to the simplest situation in which it occurs. One page is the 
largest program we can reasonably type by hand. If a larger amount of code is needed to demonstrate 
the error, send us a magtape or single density floppy. Unfortunately, we cannot return these. Note any 
intuitions you have about possible causes of the trouble. Remember: WE MUST EE ABLE TO 
REPRODUCE THE TROUBLE HERE. 


OUR RESPONSE 


It's already fixed or Fixed in next release. 

You will automatically receive a copy of a release in which the problem is fixed, if your Designated 
Contact Person has signed the Conditional Update Request on the front of this form. 

Maybe a bug, but ... 

Documentation problems, customer errors, obscure "features" or inherent limitations in our 
implementation can each cause trouble. We will help you work around the problem and/or 
supplement our documentation in these cases. Please understand that our support is limited to 
correcting problems with our software and does not include applications programming. 

In any case — 

We will send you. a written response within a month. 
























* 


Trouble Report 

See instructions on reverse side. 

CUSTOMER IDENTIFICATION 

Your Name ___—_ Designated Contact Person (if different) -—— 

Conditional Update Request: If the Trouble Report pertains to a problem that has been fixed or will be fixed in the next release, this signature constitutes a request for an 
update which Oregon Software will provide under the terms of the existing software license and/or support agreements. 



Date 

/ 

/ 

.signature,....—- -- 

_ License Number- ...- 

(wUiiipduiy -—- 

Date Submitted 

/ 

/ 

Address---——- 

Telephone ( ) 


ext. 


Country 

_ Zip/Postal Code 


City-—- 

Processor Model -—— 

Processor Options (EIS. FIS. FPP FPA. etc.)-- 




pstribution Medium_—- Attachments (Listings. Magtape, etc.) 

Software and Version_— Operating System and Version- 


PROBLEM DESCRIPTION 

( ) Major Problem ( ) Minor Problem ( ) Suggestion ( ) Inquiry 

If the problem could have been avoided by better documentation, explain below. 

' the problem is intermittent, outline below the conditions under which the problem seems to occur. 

Describe the problem (use additional sheets if necessary): 






— 

——i—. 



iL 




Log Number-—- 

)ate Assigned-/-/ 

Assigned to--—-— 

Date of Response to Customer-/-»_/ 

( ) Circulate 


Title_ 

Problem Type. 


Summary of Action 


Oregon 

Software 

6915 S.W. Macadam Avenue 
Portland, Oregon 97201, USA 
503/245-2202 
TWX: 910-464-4779 


Copyright© 1981 Oregon Software. Printed in USA May 1981 


OS-116 

































































